@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,189 @@
+# Skill: Checkbox
+
+Checkbox field supporting single boolean toggle, multi-selection mode, and optional card-style variant.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders one or more checkboxes. Supports three usage modes: (1) a single boolean checkbox, (2) a multi-select list of checkboxes bound to a reference list, and (3) a card-style selectable grid. Display mode shows the true/false label rather than the raw boolean.
+
+## Pega Metadata
+
+- **Pega Name:** `Checkbox`
+- **Type / Subtype:** `Field` / `Boolean`
+- **Registration key:** `Checkbox` (in the project's component map)
+
+> **Important naming note:** The component's export name should avoid conflicts with the design system's checkbox widget (e.g., use `CheckboxComponent` as the export name). Register it under the key `Checkbox` in the project's component map.
+
+## Inputs (component-specific)
+
+> Note: The Checkbox input contract overrides `value` to be a boolean (not a string), while inheriting all other fields from the project's field input contract.
+
+| Name                   | Type                 | Description                                                          |
+| ---------------------- | -------------------- | -------------------------------------------------------------------- |
+| `value`                | `boolean` (optional) | Checked state for single-mode checkbox                               |
+| `caption`              | `string` (optional)  | Label shown next to the single checkbox (not the group label)        |
+| `trueLabel`            | `string` (optional)  | Display text when `value` is `true` (used in display modes)          |
+| `falseLabel`           | `string` (optional)  | Display text when `value` is `false` (used in display modes)         |
+| `selectionMode`        | `string` (optional)  | `'multi'` — enables multi-selection mode from a datasource list      |
+| `datasource`           | `any` (optional)     | Options source for multi/card modes                                  |
+| `selectionKey`         | `string` (optional)  | The property path used as the key in selection list                  |
+| `selectionList`        | `any` (optional)     | Property path for the reference list (multi mode)                    |
+| `primaryField`         | `string`             | Primary display field for multi/card mode                            |
+| `readonlyContextList`  | `any`                | Array of currently selected items (for multi/card read-only display) |
+| `referenceList`        | `string`             | Reference list property path                                         |
+| `variant`              | `string` (optional)  | `'card'` — renders options as selectable card grid                   |
+| `hideFieldLabels`      | `boolean`            | Hide field labels inside card variant                                |
+| `additionalProps`      | `any`                | Extra inputs passed to card or checkbox                              |
+| `imagePosition`        | `string`             | Card image position                                                  |
+| `imageSize`            | `string`             | Card image size                                                      |
+| `showImageDescription` | `string`             | Whether to show image description                                    |
+| `renderMode`           | `string`             | `'ReadOnly'` — sets read-only mode alongside `readOnly` input        |
+| `image`                | `string`             | Image field path for card variant                                    |
+
+## Implementation Structure
+
+Follow this exact structure. The export name should avoid collision with the design system's checkbox widget.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList` and `SelectableCard`), the project's event-commit utility, and the project's instruction helpers (`insertInstruction`, `deleteInstruction`, `updateNewInstuctions`) for multi-selection reference list management. Define the input contract by overriding `value` to be an optional boolean (rather than the string from the base field input contract) and adding all the component-specific fields listed in the inputs table above.
+
+**Styling notes (design-system agnostic):** a vertical checkbox column layout (flex, column direction), and for the card variant a CSS grid layout (`repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, equal row heights, small gap).
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `FieldValueList` and `SelectableCard` via the project's component registry.
+2. **Receive inputs** — all the standard field inputs plus the component-specific ones; notably alias `readonlyContextList` to `selectedvalues` for readability.
+3. **Derived flags** — `readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly` and `helperTextToDisplay = validatemessage || helperText`.
+4. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name.
+5. **Local state** — `checked` initialized to `false`.
+6. **Sync from store** — a lifecycle effect watching `value` updates `checked` whenever it changes.
+7. **Reference list init** — a lifecycle effect watching the PConnect instance: when `referenceList?.length > 0 && !readOnlyMode`, call `thePConn.setReferenceList(selectionList)` followed by `updateNewInstuctions(thePConn, selectionList)`.
+8. **Display mode returns** — note these use `caption` (not `label`) as the display name: `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` with value set to `trueLabel` when `value` is true, `falseLabel` otherwise, the latter with a stacked variant.
+9. **Event handlers** — see the Behavioral Contract below for the exact logic of each variant's change/blur handlers.
+10. **Branch: card variant** (`variant === 'card'`) — return early with a heading, a CSS grid wrapper, and a `SelectableCard`; see the Behavioral Contract "Card" section for full input wiring.
+11. **Branch: multi-select** (`selectionMode === 'multi'`) — build a list of checkbox controls from `datasource.source`; see the Behavioral Contract "Multi-select" section.
+12. **Branch: single checkbox** (default) — a single checkbox control with `checked` state; see the Behavioral Contract "Single checkbox" section.
+13. **Main return** — a wrapper containing (in order): the group label (`label`, hidden when `hideLabel`), the checkbox group content built in step 11 or 12, and the helper text (`helperTextToDisplay`); the wrapper carries `required` and an error state driven by `status === 'error'`.
+
+## Behavioral Contract
+
+### Common
+
+1. **Read-only determination:** `readOnlyMode = renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly`.
+2. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+3. **Local state:** Maintain `checked` (boolean) initialized to `false`. A lifecycle effect watching `value` updates `checked`.
+4. **Reference list init:** A lifecycle effect watching the PConnect instance — if `referenceList?.length > 0 && !readOnlyMode`, call `thePConn.setReferenceList(selectionList)` and `updateNewInstuctions(thePConn, selectionList)`.
+5. **`handleCheckboxChange(event, item)`** — shared by card and internal usage: when the checkbox is checked, call `insertInstruction(thePConn, selectionList, selectionKey, primaryField, item)`; otherwise call `deleteInstruction(thePConn, selectionList, selectionKey, item)`. Either way, finish by calling `thePConn.clearErrorMessages({ property: selectionList })`.
+
+### Variant: Single checkbox (default)
+
+Render a single checkbox with:
+
+- Checked state bound to `checked`
+- Change handler wired only when not read-only
+- Blur handler wired only when not read-only
+- Label = `caption` (next to checkbox)
+- Group label = `label` (above, hidden if `hideLabel`)
+- **On change:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the checked boolean.
+- **On blur:** Validate via `pConn.getValidationApi().validate(event.target.checked)`.
+
+### Variant: Multi-select (`selectionMode === 'multi'`)
+
+Render a list of checkboxes from `datasource.source`:
+
+- Extract the data field key: the second segment of `selectionKey` split by `.`.
+- For each element in `datasource.source`:
+  - Checked: `selectedvalues?.some?.(data => data[dataField] === element.key)`
+  - Label: `element.text ?? element.value`
+  - **On change:** When the checkbox is checked, call `insertInstruction(thePConn, selectionList, selectionKey, primaryField, { id: element.key, primary: element.text ?? element.value })`; otherwise call `deleteInstruction(thePConn, selectionList, selectionKey, { id: element.key, primary: element.text ?? element.value })`. Either way, finish by calling `thePConn.clearErrorMessages({ property: selectionList, category: '', context: '' })`.
+  - **On blur:** `thePConn.getValidationApi().validate(selectedvalues, selectionList)`
+  - Test id: `${testId}:${element.value}`
+- Layout: vertical column (flex, column direction).
+
+### Variant: Card (`variant === 'card'`)
+
+Return early (before multi/single logic) with heading + CSS Grid + `SelectableCard`:
+
+- Build common configuration by spreading `additionalProps` and adding `className: 'standard'`, `disabled`, `readOnly`, and `onClick` taken from the PConnect actions API.
+- Grid: `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, equal row heights, gap `0.5rem`.
+- `SelectableCard` inputs:
+  - Common configuration spread, `testId`, `displayMode`, `getPConnect`
+  - `type='checkbox'`
+  - `dataSource` set to `datasource`
+  - `readOnly` set to `renderMode === 'ReadOnly' || displayMode === 'DISPLAY_ONLY' || readOnly`
+  - `recordKey` set to the last segment of `selectionKey`
+  - `cardLabel` set to the last segment of `primaryField`
+  - `readOnlyList` set to `selectedvalues`
+  - `hideFieldLabels`
+  - `showNoValue` set to true when read-only mode is active and `selectedvalues.length === 0`
+  - `image` config object bundling `imagePosition`, `imageSize`, `showImageDescription`, an `imageField` derived by taking the last segment of the `image` input path, and an `imageDescription` derived by taking the last segment of the `imageDescription` path found on `thePConn.getRawMetadata().config`.
+  - `onChange`: stop event propagation, resolve the record key by taking the last segment of `selectionKey`, find the matching item in `datasource.source` whose field at that key equals the event target's `id` (defaulting to an empty object if not found), then call `handleCheckboxChange` with an item shaped as `{ id: selectedItem[recordKey], primary: selectedItem[recordKey] }`.
+  - `onBlur`: `() => thePConn.getValidationApi().validate(selectedvalues, selectionList)`
+
+## Display Mode Rendering
+
+Display mode uses `caption` (not `label`) and shows the true/false label:
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `caption` (or empty when `hideLabel` is true) and `value` set to `trueLabel` when `value` is true, `falseLabel` otherwise.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked variant.
+
+## Read-Only Rendering
+
+Single mode: Set the read-only attribute on the checkbox element; disable the change/blur handlers.
+Multi/Card mode: The `readOnlyMode` flag prevents `insertInstruction`/`deleteInstruction`; cards show `readOnlyList`.
+
+## Visual Specifications
+
+### Standard / Multi-select
+
+| Property          | Value                                           |
+| ----------------- | ----------------------------------------------- |
+| Checkbox size     | Default (24px)                                  |
+| Label placement   | End (right of checkbox)                         |
+| Group label       | Legend/label above group, hidden if `hideLabel` |
+| Layout            | Single: single row. Multi: vertical column      |
+| Helper text       | Below group                                     |
+| Error state       | Red text/border on helper                       |
+| Disabled/readOnly | Greyed out, pointer-events none                 |
+
+**Visual-only styling notes:** The checkbox group uses a vertical flex column with a small gap between items; each checkbox label row is a flex container with center-aligned items, a small gap between the input and text, and a pointer cursor. Disabled checkbox inputs are shown at reduced opacity.
+
+### Card Variant
+
+| Property | Value                                                                                             |
+| -------- | ------------------------------------------------------------------------------------------------- |
+| Layout   | CSS Grid `repeat(auto-fit, minmax(min(100%, 40ch), 1fr))`, row height equal (`1fr`), gap `0.5rem` |
+| Heading  | Heading element with no top/bottom margin                                                         |
+
+## Edge Cases & Special Logic
+
+- **Export name should avoid collision** with the design system's checkbox widget.
+- **Display mode uses `caption`** (not `label`) for the field name. This is unique to Checkbox.
+- **`readonlyContextList`** is aliased to `selectedvalues` — use `selectedvalues` everywhere in the component body.
+- **`handleCheckboxChange`** (card mode): Stops event propagation before processing. Finds the selected item from `datasource.source` by matching `item[recordKey] === e.target.id`.
+- `updateNewInstuctions` is called on mount to sync reference list state.
+- `clearErrorMessages` is called after every multi-select change.
+- Card variant returns early (before multi/single branch logic).
+- Multi-select blur handler validates with both `selectedvalues` and `selectionList` as arguments.
+
+## Dependencies
+
+- The project's instruction helpers (`insertInstruction`, `deleteInstruction`, `updateNewInstuctions`) — for multi-selection reference list management.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- The project's component registry, resolving `SelectableCard` — for card variant.
+
+## Design System Mapping
+
+**UI control type:** Single or multi-select checkbox (boolean or list).
+
+When implementing in a specific design system, map the following:
+
+- **Single checkbox** → use the DS's checkbox component with a label to the right
+- **Multi-select** → render a list of checkboxes in a vertical flex column
+- **Card variant** → delegate to the `SelectableCard` component in a CSS grid
+- **Group wrapper** → use the DS's form control/form group with legend/label, error state, and helper text
+- **Read-only** → disable the checkbox inputs; for cards, show the read-only list

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

@@ -0,0 +1,136 @@
+# 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, input contract, 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 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:** A lifecycle effect watching `value` updates `values` (converted to string).
+3. **Helper text:** `helperTextToDisplay = validatemessage || helperText`.
+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) 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 the project's formatting helper with the currency options derived from `currencyISOCode`:
+
+- **`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 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 the read-only attribute on the input element. Switch the visual style to flat/borderless. The blur handler is omitted.
+
+## Visual Specifications
+
+| Property       | Standard (editable)          | Read-only       |
+| -------------- | ---------------------------- | --------------- |
+| Width          | 100%                         | 100%            |
+| Size           | Small                        | Small           |
+| 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 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 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.
+- 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 ?? ''`.
+- 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 — 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:**
+
+- 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.
+
+When implementing in a specific design system, map the following:
+
+- **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

@@ -0,0 +1,126 @@
+# 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, input contract, 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` (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 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 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: 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 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), 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:** 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 the project's formatting helper with format type `'date'` and options `{ format: dateFormatInfo.dateFormatString }`:
+
+- **`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`, passing all inputs through. 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 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
+
+- 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.
+
+When implementing in a specific design system, map the following:
+
+- **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)

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

@@ -0,0 +1,115 @@
+# 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, input contract, 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 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 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:** 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 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 the project's formatting helper with format type `'datetime'` and options `{ format: '<dateFormatString> hh:mm a' }`:
+
+- **`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 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
+
+| 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 the timezone-aware date instance is invalid, commit an empty string `''`.
+- Commits on **change** (picker selection), not on blur.
+- The date library's timezone plugin is required for timezone-aware conversions.
+
+## Dependencies
+
+- 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.
+
+When implementing in a specific design system, map the following:
+
+- **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)