@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 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.
+> **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,169 +14,75 @@ Renders a numeric input formatted as a currency value. Displays the correct curr
 
 - **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';
-```
-
-## Component Skeleton
-
-Follow this exact structure. Replace `<NumericFormatInput>` and `<TextFieldWidget>` with equivalents from your chosen design system / numeric format library.
-
-```typescript
-import { useEffect, useState } from 'react';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-import handleEvent from '../../helpers/event-utils';
-import { format } from '../../helpers/formatters';
-import { getCurrencyCharacters, getCurrencyOptions } from './currency-utils';
-
-// ── Props interface ──────────────────────────────────────────
-interface CurrencyProps extends PConnFieldProps {
-  currencyISOCode?: string;
-  allowDecimals: boolean;
-}
-
-// ── Component ────────────────────────────────────────────────
-export default function Currency(props: CurrencyProps) {
-  // 1. Registry lookups
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  // 2. Destructure props
-  const {
-    getPConnect, label, required, disabled, value = '',
-    validatemessage, status, readOnly, testId,
-    helperText, displayMode, hideLabel,
-    currencyISOCode = 'USD', placeholder, allowDecimals,
-  } = props;
-
-  // 3. PConnect setup
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-
-  // 4. Derived values
-  const helperTextToDisplay = validatemessage || helperText;
-  const testProps: any = { 'data-test-id': testId };
-
-  // 5. State
-  const [values, setValues] = useState(value.toString());
-
-  // 6. useEffect: sync from store — deps: [value]
-  useEffect(() => { setValues(value.toString()); }, [value]);
-
-  // 7. Currency symbol lookup
-  const theSymbols = getCurrencyCharacters(currencyISOCode);
-  const theCurrSym = theSymbols.theCurrencySymbol;
-  const theCurrDec = theSymbols.theDecimalIndicator;
-  const theCurrSep = theSymbols.theDigitGroupSeparator;
-
-  // 8. Formatted value for display modes (computed eagerly, before display mode check)
-  const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
-  const formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
-
-  // 9. Read-only prop object
-  let readOnlyProp = {};
-  if (readOnly) {
-    readOnlyProp = { readOnly: true };
-  }
-
-  // 10. Currency format config object
-  const currencyProp = {
-    prefix: theCurrSym,
-    decimalSeparator: theCurrDec,
-    thousandSeparator: theCurrSep,
-  };
-
-  // 11. 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" />;
-  }
-
-  // 12. Event handlers
-  function currOnBlur() {
-    handleEvent(actions, 'changeNblur', propName, values);
-  }
-  const handleChange = (val) => { setValues(val.value); };
-
-  // 13. Main render — numeric format input
-  //     Key props to pass to your numeric format component:
-  //     - valueIsNumericString: true
-  //     - value: values
-  //     - ...currencyProp (prefix, decimalSeparator, thousandSeparator)
-  //     - decimalScale: allowDecimals !== false ? 2 : 0
-  //     - fixedDecimalScale: allowDecimals
-  //     - onValueChange: (val) => handleChange(val)
-  //     - onBlur: !readOnly ? currOnBlur : undefined
-  //     - variant: readOnly ? 'standard' : 'outlined'
-  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
-  //     - required, disabled, error: status === 'error'
-  //     - inputProps: { ...readOnlyProp, inputProps: { ...testProps } }
-  return <NumericFormatInput ... />;
-}
-```
+- **Registration key:** `Currency` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Name              | 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`, decimal scale is 0. If `true`, fixed 2 decimal places shown. |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure. Replace the numeric-format input with an equivalent from your chosen design system / numeric format library.
+
+**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 symbol/separator lookup), and the project's formatting helpers (for display-mode value formatting). It also uses a numeric-format masking library for locale-aware input display. Define the input contract as an extension of the project's field input contract, adding an optional `currencyISOCode` and a required `allowDecimals` boolean.
+
+**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`, `testId`, `helperText`, `displayMode`, `hideLabel`, `currencyISOCode` (default `'USD'`), `placeholder`, `allowDecimals`.
+3. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name.
+4. **Derived values** — `helperTextToDisplay = validatemessage || helperText` and a test-id attribute built from `testId`.
+5. **Local state** — `values` initialized from `value.toString()`.
+6. **Sync from store** — a lifecycle effect watching `value` updates `values` (as a string) whenever it changes.
+7. **Currency symbol lookup** — derive the currency symbol, decimal indicator, and digit group separator via the project's currency utility helpers using `currencyISOCode`.
+8. **Formatted value for display modes** — computed eagerly, before the display-mode check: obtain the currency formatting options via the project's currency options helper, then compute the formatted value using the project's formatting helper with the component's type name (from `pConn.getComponentName()?.toLowerCase()`) as the format key and the currency options.
+9. **Read-only flag** — build a read-only configuration, set to mark the input read-only only when `readOnly` is true.
+10. **Currency format configuration** — build a configuration object bundling the currency symbol as prefix, the decimal indicator as decimal separator, and the digit group separator as thousands separator.
+11. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the formatted value, the latter with a stacked variant.
+12. **Event handlers** — 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.
+13. **Render** — a numeric-format input configured with: value-is-numeric-string flag, current `values`, the currency format configuration spread (prefix, decimal separator, thousands separator), decimal scale set to `2` when `allowDecimals !== false` else `0`, fixed decimal scale set to `allowDecimals`, the value-change handler, the blur handler wired only when not read-only, an outlined style when editable or flat/borderless style when read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, 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. **Test ID prop:** Build `testProps = { 'data-test-id': testId }` — passed via `inputProps` on the inner input element.
-5. **Currency symbols:** Derive from `getCurrencyCharacters(currencyISOCode)`:
-   - Returns `{ theCurrencySymbol, theDecimalIndicator, theDigitGroupSeparator }`.
+4. **Test ID:** Build a test-id attribute from `testId` — passed on the inner input element.
+5. **Currency symbols:** Derive from the project's currency utility helpers using `currencyISOCode`:
+   - Returns the currency symbol, decimal indicator, and digit group separator.
    - Default (USD): `$`, `.`, `,`.
-6. **Formatted value:** Computed eagerly (before display mode check):
-   ```
-   const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
-   const formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
-   ```
-7. **Read-only prop:** `let readOnlyProp = {}; if (readOnly) readOnlyProp = { readOnly: true };`
-8. **Currency format config:**
-   ```
-   const currencyProp = {
-     prefix: theCurrSym,
-     decimalSeparator: theCurrDec,
-     thousandSeparator: theCurrSep,
-   };
-   ```
-9. **Numeric format props (merged at render):**
-   - `valueIsNumericString: true`
-   - `value: values` (local state string)
-   - `...currencyProp` (spread prefix + separators)
-   - `decimalScale: allowDecimals !== false ? 2 : 0`
-   - `fixedDecimalScale: allowDecimals`
-   - `onValueChange: (val) => setValues(val.value)`
-   - `onBlur: !readOnly ? currOnBlur : undefined`
-   - `variant: readOnly ? 'standard' : 'outlined'`
-   - Input slot/props: `{ ...readOnlyProp, inputProps: { ...testProps } }`
-10. **On value change:** `setValues(val.value)` — raw numeric string from the format library's callback object.
-11. **On blur:** `handleEvent(actions, 'changeNblur', propName, values)` — commits local state to store.
+6. **Formatted value:** Computed eagerly (before display mode check) using the project's formatting helper with the component's type name as the format key and the currency options.
+7. **Read-only flag:** Mark the input read-only only when `readOnly` is true.
+8. **Currency format configuration:** Bundle the currency symbol as prefix, decimal indicator as decimal separator, and digit group separator as thousands separator.
+9. **Numeric format configuration (merged at render):**
+   - Value-is-numeric-string: true
+   - Value: `values` (local state string)
+   - Currency format configuration spread (prefix + separators)
+   - Decimal scale: `allowDecimals !== false ? 2 : 0`
+   - Fixed decimal scale: `allowDecimals`
+   - Value-change handler: updates `values` with the raw numeric string
+   - Blur handler: wired only when not read-only
+   - Visual style: outlined when editable, flat/borderless when read-only
+10. **On value change:** Update `values` with the raw numeric string from the format library's callback object.
+11. **On blur:** Commit local state to store via the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`.
 
 ## Display Mode Rendering
 
-Format the value before display using a currency formatter with `currencyISOCode`:
+Format the value before display using the project's formatting helper with the currency options derived from `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' />`.
+- **`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.
 
-The `formattedValue` uses the locale and currency from `currencyISOCode` to produce a localized string (e.g., `$1,234.56`).
+The formatted value 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}`).
+Keep the numeric format input but set the read-only attribute on the input element. Switch the visual style to flat/borderless. The blur handler is omitted.
 
 ## Visual Specifications
 
@@ -184,32 +90,32 @@ Keep the numeric format input but set `readOnly: true` on the input element. Swi
 | -------------- | ---------------------------- | --------------- |
 | Width          | 100%                         | 100%            |
 | Size           | Small                        | Small           |
-| Variant        | Outlined                     | Standard (flat) |
+| Variant        | Outlined                     | Flat/borderless |
 | 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      | —               |
+| Placeholder    | From the `placeholder` input | —               |
 
 ## 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 set directly to `allowDecimals` (boolean). `decimalScale` uses `allowDecimals !== false ? 2 : 0` (note: `!== false` means undefined/missing also gives 2 decimals).
+- **`allowDecimals` vs fixed decimal scale:** The fixed decimal scale flag is set directly to `allowDecimals` (boolean). Decimal scale uses `allowDecimals !== false ? 2 : 0` (note: `!== false` means undefined/missing also gives 2 decimals).
 - The input stores the raw numeric string (e.g., `'1234.56'`) in state and in the Pega store — not the formatted display string.
-- `formattedValue` is computed eagerly (before display mode check) using `pConn.getComponentName()?.toLowerCase()` as the format type — this resolves to `'currency'`.
-- `data-test-id` is passed via nested `slotProps.input.inputProps` (or `InputProps.inputProps` depending on design system) — not on the outer wrapper.
+- The formatted value is computed eagerly (before display mode check) using `pConn.getComponentName()?.toLowerCase()` as the format type — this resolves to `'currency'`.
+- The test-id attribute is passed on the inner input element, not on the outer wrapper.
 - `placeholder` defaults to `''` if undefined: `placeholder ?? ''`.
-- Variant switches between `'outlined'` (editable) and `'standard'` (read-only) — this is design-system specific but the visual intent is: bordered input vs flat/borderless.
+- Visual style switches between outlined (editable) and flat/borderless (read-only) — this is design-system specific but the visual intent is: bordered input vs flat/borderless.
 
 ## 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.
+- A numeric formatting library — handles locale-aware separators, prefix, and decimal scale.
+- 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 currency utility helpers — for currency symbol, decimal indicator, and digit group separator lookup.
+- The project's currency options helper — for formatting options based on ISO code.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 **For CSS-only / design-system-agnostic implementations:**
 
@@ -220,11 +126,11 @@ Keep the numeric format input but set `readOnly: true` on the input element. Swi
 
 **UI control type:** Currency / numeric formatted input with prefix symbol.
 
-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">` + custom numeric formatting logic                     |
-| MUI                | `NumericFormat` (from `react-number-format`) with `customInput={TextField}` |
-| Ant Design         | `<InputNumber prefix="$" precision={2} />`                                  |
-| Chakra UI          | `<NumberInput>` + custom formatting                                         |
+- **Numeric format input** → use a numeric masking library compatible with the project's framework, or implement custom input masking
+- **Currency prefix** → the currency symbol derived from the ISO code
+- **Decimal/thousands separators** → derive from the currency utility helpers
+- **Decimal scale** → 2 when decimals allowed, 0 otherwise
+- **Read-only** → flat/borderless style with read-only attribute
+- **Error state** → the DS's error/danger visual state

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

@@ -2,7 +2,7 @@
 
 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.
+> **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,162 +14,68 @@ Renders a date picker input. Stores dates as `YYYY-MM-DD` strings. Displays date
 
 - **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 ... />;
-}
-```
+- **Registration key:** `Date` (in the project's component map)
+
+> **Important naming note:** The component's export name should avoid conflicts with the platform's built-in `Date` global (e.g., use `DateField` as the import alias). Register it under the key `Date` 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-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, the project's formatting helpers (for display-mode value formatting), and the project's date-format utility (for locale-aware format strings). It also uses a date manipulation library (for parsing/formatting/validation) and a date picker UI component (for the calendar popup). Define the input contract as the project's field input contract with no additional fields.
+
+**Helper function (top-level, outside the component):** `getFormattedDate(date)` returns the date as a `YYYY-MM-DD` string suitable for posting to the server, built from the date object's year, month (converted from 0-indexed to 1-indexed and zero-padded), and day (zero-padded).
+
+**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`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`.
+3. **Local state** — `dateValue` typed as a date object or null, initialized from `value` (parsed via the date library) or `null` when `value` is empty.
+4. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`.
+5. **Date format info** — start from the project's default date-format info and mutate its `dateFormatString`, `dateFormatStringLC`, and `dateFormatMask` properties with the locale-specific values returned by the project's date-format utility.
+6. **Sync from store** — a lifecycle effect watching `value` updates `dateValue` (parsed via the date library) whenever it changes.
+7. **Display mode returns** — for both `DISPLAY_ONLY` and `STACKED_LARGE_VAL`, compute the formatted date using the project's formatting helper with format type `'date'` and options `{ format: dateFormatInfo.dateFormatString }`, then return `FieldValueList` with that value (the latter with a stacked variant).
+8. **Read-only return (before event handlers)** — when `readOnly` is true, render the `TextInput` component with all inputs passed through directly (full delegation).
+9. **Test ID** — build a test-id attribute from `testId`.
+10. **Change handler — only commits valid dates** — given a selected date: if it is valid, update local state and immediately commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the formatted `YYYY-MM-DD` string from `getFormattedDate(date)`; invalid or incomplete dates are ignored entirely (no state update, no commit).
+11. **Render** — a date picker configured with: `label`, `disabled`, current `dateValue`, display format set to the locale-aware date format string, the change handler, and a nested text-field slot configured with `required`, an outlined style, small size, placeholder set to the lowercase format string (e.g., `mm/dd/yyyy`), an error state when `status === 'error'`, `helperText: helperTextToDisplay`, and the test-id attribute applied to the input element.
 
 ## 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))`.
+1. **Local state:** Maintain `dateValue` as a date object or null. Initialize: `value ? parse(value) : null`.
+2. **Sync from store:** A lifecycle effect watching `value` updates `dateValue` (parsed via the date library).
 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;
-   ```
+4. **Date format info:** Start from the project's default date-format info, then **mutate** its properties with locale-specific values from the project's date-format utility — specifically, copy the fresh `dateFormatString`, `dateFormatStringLC`, and `dateFormatMask` from the freshly-computed locale info onto the shared default object.
 5. **On change (valid date selected):**
-   - Guard: `if (date && date.isValid())` — skip invalid/incomplete dates.
-   - Update state: `setDateValue(date)`.
+   - Guard: only proceed if the date is valid — skip invalid/incomplete dates.
+   - Update state with the selected 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.
+   - Commit immediately via the project's event-commit utility with event type `'changeNblur'`, the property name, and the formatted date.
+6. **Read-only:** Return early by delegating to the `TextInput` component.
+7. **Placeholder:** Use the lowercase format string from the date-format info (e.g., `'mm/dd/yyyy'`).
+8. **Test ID:** Build a test-id attribute from `testId` and pass via the text field slot's input element.
 
 ## 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')}`;
-}
-```
+Top-level pure function (outside the component), named `getFormattedDate(date)`. It builds a `YYYY-MM-DD` string using the date object's internal properties: the year as-is, the month incremented by one (since it's 0-indexed) and zero-padded to two digits, and the day zero-padded to two digits, joined with hyphens.
 
-**Note:** `date.$y` = year, `date.$M` = month (0-indexed), `date.$D` = day. If using a different date library, replace with equivalent accessors.
+**Note:** If using a different date library, replace with equivalent accessors for year, month (0-indexed), and day.
 
 ## Display Mode Rendering
 
-Format the value before display using `format(value, 'date', { format: dateFormatInfo.dateFormatString })`:
+Format the value before display using the project's formatting helper with format type `'date'` and options `{ 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).
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the formatted date.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+- Both modes compute the formatted date from the raw `value` input (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).
+Delegate to `TextInput`, passing all inputs through. The raw `YYYY-MM-DD` string is displayed as-is (or formatted by `TextInput`'s read-only rendering).
 
 ## Visual Specifications
 
@@ -190,32 +96,31 @@ Delegate to `TextInput`: `return <TextInput {...props} />`. The raw `YYYY-MM-DD`
 
 - 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.
+- Invalid/incomplete dates (e.g., partially typed) are ignored — only commit when the date is valid.
+- Locale format info is derived at render time from the project's date-format utility — this reads the Pega environment locale.
+- **Render ordering:** display modes → readOnly return → test-id → change handler → main render. The readOnly check comes BEFORE handler definitions.
+- The default date-format info object is mutated in place (not spread-copied) — this is the existing pattern, maintain it.
+- `getFormattedDate` accesses date library internals for year, month (0-indexed), day — 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.
+- A date manipulation library (for parsing, formatting, validity checking).
+- A date picker UI component (for the calendar popup).
+- The project's date-format utility — for locale-aware format string.
+- The project's default date-format info — default fallback.
+- 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 `TextInput` — for read-only delegation.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 ## Design System Mapping
 
 **UI control type:** Date picker with calendar popup.
 
-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="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">`                 |
+- **Date picker** → use the DS's date picker component or a compatible third-party date picker
+- **Date format** → pass the locale-aware format string from the project's date-format utility
+- **Placeholder** → the lowercase version of the format string
+- **Read-only mode** → delegate to the `TextInput` component
+- **Commit behavior** → commit on valid date selection (not on blur)