@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,164 @@
+# Skill: TextArea
+
+Multi-line text input field that 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 an editable multi-line text area. Used for long-form text input such as descriptions, notes, or comments. Similar to `TextInput` but allows multiple lines with configurable min/max rows.
+
+## Pega Metadata
+
+- **Pega Name:** `TextArea`
+- **Type / Subtype:** `Field` / `Text` (multi-line)
+- **Registration key:** `TextArea` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop            | Type             | Description                                                |
+| --------------- | ---------------- | ---------------------------------------------------------- |
+| `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the textarea |
+
+All other props come from `PConnFieldProps`. Import type as:
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Component Skeleton
+
+Similar to TextInput but multiline with fixed rows. Does NOT delegate to TextInput in read-only mode.
+
+```typescript
+import { useEffect, useState } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface TextAreaProps extends PConnFieldProps {
+  fieldMetadata?: any;
+}
+
+export default function TextArea(props: TextAreaProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId, fieldMetadata,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+  const helperTextToDisplay = validatemessage || helperText;
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const maxLength = fieldMetadata?.maxLength;
+
+  // 3. State
+  const [inputValue, setInputValue] = useState('');
+  let readOnlyProp = {};
+
+  // 4. useEffect: sync from store — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 5. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 6. Read-only: set readOnlyProp (do NOT delegate to TextInput — preserve multiline)
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 7. Test ID + handlers
+  const testProps: any = { 'data-test-id': testId };
+  function handleChange(event) { setInputValue(event?.target?.value); }
+  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
+
+  // 8. Main render — multiline text input
+  //    Key props:
+  //    - multiline: true, minRows: 5, maxRows: 5
+  //    - fullWidth, variant: readOnly ? 'standard' : 'outlined', size: 'small'
+  //    - value: inputValue, onChange: handleChange
+  //    - onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - slotProps: { input: { ...readOnlyProp, inputProps: { maxLength, ...testProps } } }
+  return <TextAreaWidget ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `''`.
+2. **Sync from store:** `useEffect` watching `value` prop — call `setInputValue(value)` whenever `value` changes.
+3. **On change:** Update local `inputValue` state only (do NOT commit to store on every keystroke).
+4. **On blur:** Commit to store by calling `handleEvent(actions, 'changeNblur', propName, inputValue)`.
+5. **Read-only:** Set `readOnly` attribute on the textarea; use visually borderless ("standard") variant. Omit `onBlur` handler: `onBlur={!readOnly ? handleBlur : undefined}`.
+6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the textarea's `maxLength` attribute.
+7. **Row sizing:** Fixed at `minRows={5}` and `maxRows={5}` — the textarea does not auto-expand; it shows a scrollbar if content exceeds 5 rows.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} />`.
+- **`STACKED_LARGE_VAL`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+- Both modes short-circuit before interactive rendering.
+
+## Read-Only Rendering
+
+Set `readOnly` on the textarea element (NOT a read-only version via `TextInput` — preserves the multiline appearance). Switch to a flat/borderless visual style. The `minRows`/`maxRows` constraint is still applied in read-only.
+
+## Visual Specifications
+
+Derived from the reference component's MUI props:
+
+| Property      | Standard (editable)                      | Read-only            |
+| ------------- | ---------------------------------------- | -------------------- |
+| Width         | 100%                                     | 100%                 |
+| Min rows      | 5                                        | 5                    |
+| Max rows      | 5 (scrollable beyond)                    | 5                    |
+| Border        | 1px solid (outlined)                     | None (standard/flat) |
+| Border radius | 4px                                      | —                    |
+| Label         | Floating label                           | Floating label       |
+| Helper text   | Below textarea                           | Below textarea       |
+| Error state   | Red border + red helper text             | —                    |
+| Resize        | Vertical resize handle (browser default) | Same                 |
+| Font size     | 0.875rem                                 | 0.875rem             |
+| Padding       | 8px 14px                                 | —                    |
+
+**CSS-only implementation notes:**
+
+- `textarea { min-height: calc(5 * 1.4375em + 16px); max-height: calc(5 * 1.4375em + 16px); overflow-y: auto; resize: vertical; }`
+- Error: `border-color: #d32f2f`
+- Read-only: `border: none; background: transparent;`
+
+## Edge Cases & Special Logic
+
+- Unlike `TextInput`, do NOT delegate to `TextInput` in read-only mode — render the textarea directly with `readOnly` set, so the multi-line appearance is preserved.
+- `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
+
+## Dependencies
+
+- `handleEvent` from `../../helpers/event-utils`
+- `getComponentFromRegistry('FieldValueList')` for display modes
+- No third-party UI libraries required
+
+## Design System Mapping
+
+**UI control type:** Multi-line text input (`<textarea>`).
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                             |
+| ------------------ | ------------------------------------------------- |
+| Default (CSS only) | `<textarea rows="5">` with floating label         |
+| MUI                | `<TextField multiline minRows={5} maxRows={5} />` |
+| Ant Design         | `<Input.TextArea rows={5} />`                     |
+| Chakra UI          | `<Textarea />`                                    |
+| Shadcn/ui          | `<Textarea />`                                    |

package/templates/react-sdk-reference/{.cursor/rules/skills/field-skills/TextContent.mdrules → .ai-common/skills/field-skills/TextContent.md}

@@ -1,8 +1,3 @@
----
-description: Field component skill: TextContent
-alwaysApply: false
----
-
 # Skill: TextContent
 
 Static text display component that renders formatted text content (paragraph or heading). Non-interactive — no form binding.
@@ -34,15 +29,43 @@ interface TextContentProps extends PConnProps {
 }
 ```
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `content` | `string` | The text string to render |
+| Prop        | Type                                                                      | Description                                       |
+| ----------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| `content`   | `string`                                                                  | The text string to render                         |
 | `displayAs` | `'Paragraph' \| 'Heading 1' \| 'Heading 2' \| 'Heading 3' \| 'Heading 4'` | How to render the text — maps to typography level |
 
+## Component Skeleton
+
+Simplest possible component — no state, no effects, just a switch on `displayAs`.
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface TextContentProps extends PConnProps {
+  content: string;
+  displayAs: 'Paragraph' | 'Heading 1' | 'Heading 2' | 'Heading 3' | 'Heading 4';
+}
+
+export default function TextContent(props: TextContentProps) {
+  const { content, displayAs } = props;
+
+  switch (displayAs) {
+    case 'Paragraph': return <p>{content}</p>;
+    case 'Heading 1': return <h1>{content}</h1>;
+    case 'Heading 2': return <h2>{content}</h2>;
+    case 'Heading 3': return <h3>{content}</h3>;
+    case 'Heading 4': return <h4>{content}</h4>;
+    default:
+      console.error(`TextContent got unexpected displayAs: ${displayAs}`);
+      return <p>{content}</p>;
+  }
+}
+```
+
 ## Behavioral Contract
 
 1. **No state, no effects** — purely presentational. Render `content` using the appropriate typography element for `displayAs`.
-2. **Mapping:** 
+2. **Mapping:**
    - `'Paragraph'` → `<p>` / body text
    - `'Heading 1'` → `<h1>`
    - `'Heading 2'` → `<h2>`
@@ -62,23 +85,39 @@ Always read-only — there is no editable state.
 
 Derived from standard HTML typography:
 
-| `displayAs` | Element | Font size | Font weight |
-|-------------|---------|-----------|-------------|
-| `Paragraph` | `<p>` / `body1` | 1rem (16px) | 400 |
-| `Heading 1` | `<h1>` | 2.5rem | 300 |
-| `Heading 2` | `<h2>` | 2rem | 300 |
-| `Heading 3` | `<h3>` | 1.75rem | 400 |
-| `Heading 4` | `<h4>` | 1.5rem | 400 |
+| `displayAs` | Element         | Font size   | Font weight |
+| ----------- | --------------- | ----------- | ----------- |
+| `Paragraph` | `<p>` / `body1` | 1rem (16px) | 400         |
+| `Heading 1` | `<h1>`          | 2.5rem      | 300         |
+| `Heading 2` | `<h2>`          | 2rem        | 300         |
+| `Heading 3` | `<h3>`          | 1.75rem     | 400         |
+| `Heading 4` | `<h4>`          | 1.5rem      | 400         |
 
 Color inherits from the surrounding text color. No padding, margin, border, or background beyond what the browser/design-system applies to the heading element.
 
 **CSS-only implementation notes:**
+
 ```css
-.text-content-h1 { font-size: 2.5rem; font-weight: 300; }
-.text-content-h2 { font-size: 2rem; font-weight: 300; }
-.text-content-h3 { font-size: 1.75rem; font-weight: 400; }
-.text-content-h4 { font-size: 1.5rem; font-weight: 400; }
-.text-content-body { font-size: 1rem; font-weight: 400; }
+.text-content-h1 {
+  font-size: 2.5rem;
+  font-weight: 300;
+}
+.text-content-h2 {
+  font-size: 2rem;
+  font-weight: 300;
+}
+.text-content-h3 {
+  font-size: 1.75rem;
+  font-weight: 400;
+}
+.text-content-h4 {
+  font-size: 1.5rem;
+  font-weight: 400;
+}
+.text-content-body {
+  font-size: 1rem;
+  font-weight: 400;
+}
 ```
 
 ## Edge Cases & Special Logic
@@ -98,9 +137,9 @@ Color inherits from the surrounding text color. No padding, margin, border, or b
 
 Listed design systems are examples only.
 
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | Native `<h1>`–`<h4>` or `<p>` |
-| MUI | `<Typography variant='h1' \| 'h2' \| 'h3' \| 'h4' \| 'body1'>` |
-| Ant Design | `<Typography.Title level={1-4}>` or `<Typography.Text>` |
-| Chakra UI | `<Heading as='h1'-'h4'>` or `<Text>` |
+| Design System      | Recommended Component                                          |
+| ------------------ | -------------------------------------------------------------- |
+| Default (CSS only) | Native `<h1>`–`<h4>` or `<p>`                                  |
+| MUI                | `<Typography variant='h1' \| 'h2' \| 'h3' \| 'h4' \| 'body1'>` |
+| Ant Design         | `<Typography.Title level={1-4}>` or `<Typography.Text>`        |
+| Chakra UI          | `<Heading as='h1'-'h4'>` or `<Text>`                           |

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

@@ -0,0 +1,174 @@
+# Skill: TextInput
+
+Single-line text input field that 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 single-line editable text field. It is the simplest and most foundational field component — used directly for free-text string properties and also delegated to by other components (e.g., `Email`, `URL`, `Date` in read-only mode).
+
+## Pega Metadata
+
+- **Pega Name:** `TextInput`
+- **Type / Subtype:** `Field` / `Text`
+- **Registration key:** `TextInput` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop            | Type             | Description                                             |
+| --------------- | ---------------- | ------------------------------------------------------- |
+| `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the input |
+
+All other props come from `PConnFieldProps`. Import type as:
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Component Skeleton
+
+The foundational field component — simplest pattern. All text-like fields (Email, URL, Integer, Phone) follow this structure with minor variations.
+
+```typescript
+import { useState, useEffect } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface TextInputProps extends PConnFieldProps {
+  fieldMetadata?: any;
+}
+
+export default function TextInput(props: TextInputProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId, fieldMetadata,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+  const maxLength = fieldMetadata?.maxLength;
+
+  // 4. State + readOnly prop
+  const [inputValue, setInputValue] = useState('');
+  let readOnlyProp = {};
+
+  // 5. useEffect: sync from store — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 6. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 7. Read-only prop
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 8. Test ID + handlers
+  const testProps: any = { 'data-test-id': testId };
+  function handleChange(event) { setInputValue(event?.target?.value); }
+  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
+
+  // 9. Main render — single-line text input
+  //    Key props:
+  //    - fullWidth, variant: readOnly ? 'standard' : 'outlined', size: 'small'
+  //    - value: inputValue, onChange: handleChange
+  //    - onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - slotProps: { input: { ...readOnlyProp, inputProps: { maxLength, ...testProps } } }
+  return <TextFieldWidget ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `value` prop (`''` default).
+2. **Sync from store:** `useEffect` watching `value` prop — call `setInputValue(value)` whenever `value` changes.
+3. **On change:** Update local `inputValue` state only (do NOT commit to store on every keystroke).
+4. **On blur:** Commit to store by calling `handleEvent(actions, 'changeNblur', propName, inputValue)`.
+5. **Read-only:** Render input with `readOnly` attribute set; use a visually borderless ("standard") variant. Do NOT skip the blur handler when readOnly — simply omit it (`onBlur={!readOnly ? handleBlur : undefined}`).
+6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the underlying input's `maxLength` attribute.
+7. **testId:** Pass as `data-test-id` attribute on the underlying `<input>` element.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} />` — display raw string value, no formatting.
+- **`STACKED_LARGE_VAL`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+- Both modes use `value` prop directly (not local state).
+- Both modes short-circuit before any interactive rendering.
+
+## Read-Only Rendering
+
+Set the `readOnly` attribute on the underlying input element. Use a visually flat/borderless style (no border box). The editable `outlined` variant switches to a `standard` (no outline) variant when read-only.
+
+## Visual Specifications
+
+Derived from the reference component's MUI props and styles:
+
+| Property        | Standard (editable)                              | Read-only               |
+| --------------- | ------------------------------------------------ | ----------------------- |
+| Width           | 100% of container                                | 100% of container       |
+| Height / size   | Small (`height ~40px`)                           | Small                   |
+| Border          | 1px solid (outlined)                             | None (standard variant) |
+| Border radius   | 4px                                              | —                       |
+| Label           | Floating label (above input when focused/filled) | Floating label          |
+| Helper text     | Shown below input                                | Shown below input       |
+| Error state     | Red border + red helper text                     | —                       |
+| Disabled        | Reduced opacity (~0.38), not-allowed cursor      | —                       |
+| Padding (input) | 8px 14px                                         | —                       |
+| Font size       | 0.875rem (14px)                                  | 0.875rem                |
+
+**CSS-only implementation notes:**
+
+- Floating label: use `<label>` positioned absolutely, translate upward on `:focus-within` or when input has value.
+- Error state: add `.error` class → border-color: `#d32f2f`; helper text color: `#d32f2f`.
+- Outlined box shadow on focus: `0 0 0 2px rgba(25, 118, 210, 0.2)`.
+
+## Edge Cases & Special Logic
+
+- If `value` prop is `undefined`, default to `''` to keep the input controlled.
+- If `readOnly` is true, the `onBlur` handler must be omitted — do not commit on blur for read-only.
+- `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
+
+## Dependencies
+
+- `handleEvent` from `../../helpers/event-utils` — for committing value to store.
+- `getComponentFromRegistry('FieldValueList')` — for display modes.
+- No third-party UI libraries required beyond a basic text input element.
+
+## Design System Mapping
+
+**UI control type:** Single-line text input (`<input type="text">`).
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                     |
+| ------------------ | --------------------------------------------------------- |
+| Default (CSS only) | `<input type="text">` with floating label pattern         |
+| MUI                | `<TextField variant='outlined' size='small' fullWidth />` |
+| Ant Design         | `<Input />`                                               |
+| Chakra UI          | `<Input />`                                               |
+| Shadcn/ui          | `<Input />`                                               |
+
+When implementing in a specific design system, map the following behaviors:
+
+- `error={status === 'error'}` → error/danger variant
+- `helperText` → helper/description slot below the input
+- `label` → field label (floating or static depending on design system)
+- `disabled` → disabled prop
+- `required` → required/asterisk indicator

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

@@ -0,0 +1,156 @@
+# Skill: Time
+
+Time picker field with 5-minute step increments, 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 time-only picker. Stores time as `HH:mm:ss` string. Displays time in 12-hour (`hh:mm a`) format. Uses `minutesStep={5}` for the picker. Delegates read-only rendering to `TextInput`.
+
+## Pega Metadata
+
+- **Pega Name:** `Time`
+- **Type / Subtype:** `Field` / `Time`
+- **Registration key:** `Time` (in `component-map.ts`)
+
+## Props (component-specific)
+
+No props beyond `PConnFieldProps`. Import type as:
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Component Skeleton
+
+No local state for time value — derived directly from `props.value` on each render.
+
+```typescript
+import dayjs from 'dayjs';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface TimeProps extends PConnFieldProps {}
+
+export default function Time(props: TimeProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+  const TextInput = getComponentFromRegistry('TextInput');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, helperText, displayMode,
+    hideLabel, testId,
+  } = props;
+  const helperTextToDisplay = validatemessage || helperText;
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+
+  // 3. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 4. Read-only return
+  if (readOnly) return <TextInput {...props} />;
+
+  // 5. Test ID
+  const testProps: any = { 'data-test-id': testId };
+
+  // 6. handleChange — commit on change (not blur)
+  const handleChange = (date) => {
+    const theValue = date && date.isValid() ? date.format('HH:mm:ss') : null;
+    handleEvent(actions, 'changeNblur', propName, theValue);
+  };
+
+  // 7. Parse time value from HH:mm:ss string
+  let timeValue: any = null;
+  if (value && Object.keys(value).length) {
+    const timeArray = value.split(':').map(itm => Number(itm));
+    timeValue = dayjs().hour(timeArray[0]).minute(timeArray[1]);
+  }
+
+  // 8. Main render — time picker
+  //    Key props:
+  //    - disabled, label, value: timeValue
+  //    - minutesStep: 5, format: 'hh:mm a'
+  //    - onChange: handleChange
+  //    - textField slot: variant 'outlined', placeholder 'hh:mm am',
+  //      required, error: status === 'error', helperText: helperTextToDisplay,
+  //      size: 'small', InputProps: { ...testProps }
+  return <TimePickerWidget ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Value format stored/committed:** `HH:mm:ss` (24-hour, e.g., `'14:30:00'`).
+2. **Value parsed for display:** Split the `HH:mm:ss` string into `[hours, minutes, seconds]` and construct a time object. Use the date library: `dayjs().hour(hours).minute(minutes)`.
+3. **Local state:** No explicit local state for the time value — the picker's controlled `value` is derived from `props.value` directly on each render.
+4. **On change:**
+   - If date is valid: `theValue = date.format('HH:mm:ss')`, else `theValue = null`.
+   - Commit immediately via `handleEvent(actions, 'changeNblur', propName, theValue)`.
+5. **Display format:** `'hh:mm a'` (12-hour with am/pm) in the picker UI.
+6. **Placeholder:** `'hh:mm am'`.
+7. **Minutes step:** 5 minutes.
+8. **Read-only:** Delegate to `TextInput`: `return <TextInput {...props} />`.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw time string, no extra formatting.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+Delegate to `TextInput`: `return <TextInput {...props} />`.
+
+## Visual Specifications
+
+| Property     | Value                            |
+| ------------ | -------------------------------- |
+| Width        | Auto (time picker natural width) |
+| Size         | Small                            |
+| Variant      | Outlined                         |
+| Format       | `hh:mm a` (12-hour)              |
+| Placeholder  | `hh:mm am`                       |
+| Minutes step | 5                                |
+| 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 — same as DateTime, this is a known date picker library quirk.
+
+## Edge Cases & Special Logic
+
+- **Null/empty value:** When `value` is empty or `Object.keys(value).length === 0`, set `timeValue = null` — do NOT try to parse an empty object.
+- **Value parsing:** Split by `:` and convert each part to a number before constructing the time object.
+- **Commits on change** (picker selection), not on blur.
+- If `date.isValid()` is false (user clears the time), commit `null`.
+
+## Dependencies
+
+- Date manipulation library (e.g., `dayjs`) — for time parsing and `format('HH:mm:ss')`.
+- Time picker UI component (e.g., `@mui/x-date-pickers/TimePicker`).
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+
+## Design System Mapping
+
+**UI control type:** Time picker (clock popup or input with am/pm selector).
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                             |
+| ------------------ | ------------------------------------------------- |
+| Default (CSS only) | `<input type="time">` (24h, no am/pm)             |
+| MUI                | `<TimePicker minutesStep={5} format='hh:mm a' />` |
+| Ant Design         | `<TimePicker format="hh:mm a" minuteStep={5} />`  |
+| Chakra UI          | Third-party time picker                           |