@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,230 @@
+# Skill: Currency
+
+Currency input field with locale-aware symbol, decimal separator, and thousands separator. Supports ISO currency codes.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a numeric input formatted as a currency value. Displays the correct currency symbol, decimal separator, and thousands separator for the given ISO currency code. Uses a numeric formatting library to handle locale-aware input. Shows formatted read-only values in display modes.
+
+## Pega Metadata
+
+- **Pega Name:** `Currency`
+- **Type / Subtype:** `Field` / `Decimal-Currency`
+- **Registration key:** `Currency` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop              | Type                | Default | Description                                                                                            |
+| ----------------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `currencyISOCode` | `string` (optional) | `'USD'` | ISO 4217 currency code (e.g., `'USD'`, `'EUR'`, `'GBP'`)                                               |
+| `allowDecimals`   | `boolean`           | —       | Whether to allow decimal input. If `false`, `decimalScale=0`. If `true`, fixed 2 decimal places shown. |
+
+All other props from `PConnFieldProps`. Import type as:
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## 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 ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
+2. **Sync from store:** `useEffect` with deps **`[value]`** → `setValues(value.toString())`.
+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 }`.
+   - 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.
+
+## Display Mode Rendering
+
+Format the value before display using a currency formatter with `currencyISOCode`:
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />` where `formattedValue = format(value, 'currency', currencyOptions)`.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+
+The `formattedValue` uses the locale and currency from `currencyISOCode` to produce a localized string (e.g., `$1,234.56`).
+
+## Read-Only Rendering
+
+Keep the numeric format input but set `readOnly: true` on the input element. Switch the visual variant to flat/borderless. The `onBlur` handler is omitted (`onBlur={!readOnly ? currOnBlur : undefined}`).
+
+## Visual Specifications
+
+| Property       | Standard (editable)          | Read-only       |
+| -------------- | ---------------------------- | --------------- |
+| Width          | 100%                         | 100%            |
+| Size           | Small                        | Small           |
+| Variant        | Outlined                     | Standard (flat) |
+| Prefix         | Currency symbol (e.g., `$`)  | Currency symbol |
+| Alignment      | Left-aligned text            | Left-aligned    |
+| Decimal places | 2 (when `allowDecimals`)     | 2               |
+| Error state    | Red border + red helper text | —               |
+| Placeholder    | From `placeholder` prop      | —               |
+
+## Edge Cases & Special Logic
+
+- **EUR uses `nl-NL` locale:** When `currencyISOCode === 'EUR'`, use NL locale for symbol/separator lookup.
+- **Fallback:** If `currencyISOCode` lookup fails, fall back to USD (`$`, `.`, `,`).
+- **`allowDecimals` vs `fixedDecimalScale`:** `fixedDecimalScale` is set directly to `allowDecimals` (boolean). `decimalScale` 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.
+- `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.
+
+## Dependencies
+
+- A numeric formatting library (e.g., `react-number-format`'s `NumericFormat`) — handles locale-aware separators, prefix, and decimal scale.
+- `format()` from `../../helpers/formatters` — for display mode value formatting.
+- `getCurrencyCharacters(currencyISOCode)` — returns `{ theCurrencySymbol, theDecimalIndicator, theDigitGroupSeparator }`.
+- `getCurrencyOptions(currencyISOCode)` — returns `{ locale, style: 'currency', currency }` for the `format()` call.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+**For CSS-only / design-system-agnostic implementations:**
+
+- The numeric format library handles the input masking. Use any numeric format library that supports prefix, decimal separator, and thousands separator configuration.
+- Alternatively, implement manually: on change, strip non-numeric chars, insert separators, prepend symbol.
+
+## Design System Mapping
+
+**UI control type:** Currency / numeric formatted input with prefix symbol.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                       |
+| ------------------ | --------------------------------------------------------------------------- |
+| Default (CSS only) | `<input type="text">` + custom numeric formatting logic                     |
+| MUI                | `NumericFormat` (from `react-number-format`) with `customInput={TextField}` |
+| Ant Design         | `<InputNumber prefix="$" precision={2} />`                                  |
+| Chakra UI          | `<NumberInput>` + custom formatting                                         |

package/templates/react-sdk-reference/.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                                  |