@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,116 +2,62 @@
 
 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.
+> **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 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`.
+Renders a time-only picker. Stores time as `HH:mm:ss` string. Displays time in 12-hour (`hh:mm a`) format. Uses 5-minute step increments 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 ... />;
-}
-```
+- **Registration key:** `Time` (in the project's component map)
+
+## Inputs (component-specific)
+
+No inputs beyond the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+No local state for the time value — it is derived directly from the `value` input on each render.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList` and `TextInput`), the project's event-commit utility, and a date/time manipulation library (for parsing and formatting time values). 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 `FieldValueList` and `TextInput` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `helperText`, `displayMode`, `hideLabel`, `testId`. Compute `helperTextToDisplay = validatemessage || helperText`, and set up the PConnect instance, actions API, and bound property name.
+3. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+4. **Read-only return** — when `readOnly` is true, render the `TextInput` component with all inputs passed through directly (full delegation).
+5. **Test ID** — build a test-id attribute from `testId`.
+6. **Change handler — commit on change, not blur** — given a selected time object: if it is valid, format it to `'HH:mm:ss'`; otherwise use `null`. Immediately commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and the formatted value — there is no separate blur-triggered commit for this field.
+7. **Parse time value from the `HH:mm:ss` string** — when `value` is present and non-empty, split it on `:` into numeric parts and construct a time object with the parsed hours and minutes to get the picker's controlled time value; otherwise the time value is `null`.
+8. **Render** — a time picker configured with: `disabled`, `label`, current time value, minutes step of `5`, display format `'hh:mm a'`, the change handler, and a nested text-field slot configured with an outlined style, placeholder `'hh:mm am'`, `required`, an error state when `status === 'error'`, `helperText: helperTextToDisplay`, small size, and the test-id attribute applied to the input element.
 
 ## 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.
+2. **Value parsed for display:** Split the `HH:mm:ss` string into `[hours, minutes, seconds]` and construct a time object using the date library.
+3. **Local state:** No explicit local state for the time value — the picker's controlled value is derived from the `value` input 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)`.
+   - If the time object is valid: format to `'HH:mm:ss'`, else use `null`.
+   - Commit immediately via the project's event-commit utility with event type `'changeNblur'`, the property name, and the formatted value.
 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} />`.
+8. **Read-only:** Delegate to `TextInput`, passing all inputs through.
 
 ## 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' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — raw time string, no extra formatting.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Delegate to `TextInput`: `return <TextInput {...props} />`.
+Delegate to `TextInput`, passing all inputs through.
 
 ## Visual Specifications
 
@@ -129,28 +75,28 @@ Delegate to `TextInput`: `return <TextInput {...props} />`.
 
 ## 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.
+- **Null/empty value:** When `value` is empty or has no content, set the time value to `null` — do NOT try to parse an empty value.
 - **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`.
+- If the time object is invalid (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.
+- A date/time manipulation library — for time parsing and formatting to `'HH:mm:ss'`.
+- A time picker UI component (for the clock popup or time selection UI).
+- 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:** Time picker (clock popup or input with am/pm selector).
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                             |
-| ------------------ | ------------------------------------------------- |
-| Default (CSS only) | `<input type="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                           |
+- **Time picker** → use the DS's time picker component or a compatible third-party picker
+- **Display format** → `'hh:mm a'` (12-hour with am/pm)
+- **Minutes step** → configure the time picker to snap to 5-minute increments
+- **Stored format** → `'HH:mm:ss'` (24-hour, committed to the Pega store)
+- **Read-only mode** → delegate to the `TextInput` component
+- **Commit behavior** → commit on valid selection (not on blur)

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

@@ -2,7 +2,7 @@
 
 URL input field with browser-native URL validation, binds to a Pega case property.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,94 +14,47 @@ Renders a single-line text input of type `url`. Provides browser-native URL form
 
 - **Pega Name:** `URL`
 - **Type / Subtype:** `Field` / `Text-URL`
-- **Registration key:** `URL` (mapped to `URLComponent` in `component-map.ts` — the component export is named `URLComponent` to avoid conflicts with the global `URL` API)
-
-## Props (component-specific)
-
-No props beyond `PConnFieldProps`. Import type as:
-
-```typescript
-import type { PConnFieldProps } from '@pega/sdk-react';
-```
-
-> **Important naming note:** Export the component as `URLComponent` (not `URL`) to avoid conflicts with the browser's built-in `URL` global. Register it in `component-map.ts` as `URL: URLComponent`.
-
-## Component Skeleton
-
-Nearly identical to TextInput — only difference is `type='url'`.
-
-```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 URLComponentProps extends PConnFieldProps {}
-
-export default function URLComponent(props: URLComponentProps) {
-  // 1. Registry lookups
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-  const TextInput = getComponentFromRegistry('TextInput');
-
-  // 2. Destructure props
-  const {
-    getPConnect, label, required, disabled, value = '',
-    validatemessage, status, readOnly, testId,
-    helperText, displayMode, hideLabel, placeholder,
-  } = props;
-  const helperTextToDisplay = validatemessage || helperText;
-  const [inputValue, setInputValue] = useState('');
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-
-  // 3. useEffect: sync — deps: [value]
-  useEffect(() => { setInputValue(value); }, [value]);
-
-  // 4. 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" />;
-  }
-
-  // 5. Read-only return
-  if (readOnly) return <TextInput {...props} />;
-
-  // 6. Handlers
-  const testProps: any = { 'data-test-id': testId };
-  const handleChange = (event) => { setInputValue(event?.target?.value); };
-  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
-
-  // 7. Main render — URL input (type='url')
-  //    Key props: same as TextInput but type: 'url'
-  //    - fullWidth, variant: 'outlined', size: 'small'
-  //    - value: inputValue, onChange, onBlur: !readOnly ? handleBlur : undefined
-  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
-  //    - required, disabled, error: status === 'error'
-  //    - slotProps: { input: { inputProps: { ...testProps } } }
-  return <TextFieldWidget type="url" ... />;
-}
-```
+- **Registration key:** `URL` (in the project's component map)
+
+> **Important naming note:** The component's export name should avoid conflicts with the platform's built-in `URL` global (e.g., use `URLComponent` as the export name). Register it under the key `URL` in the project's component map.
+
+## Inputs (component-specific)
+
+No inputs beyond the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Nearly identical to TextInput — only difference is the `url` input type.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList` and `TextInput`) and the project's event-commit utility (for committing value changes to the store). Define the input contract as the project's field input contract with no additional fields. Export the component with a name that avoids conflicts with the platform's built-in `URL` global.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `FieldValueList` and `TextInput` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`. Compute `helperTextToDisplay = validatemessage || helperText`, initialize `inputValue` local state to `''`, and set up the PConnect instance, actions API, and bound property name.
+3. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever it changes.
+4. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+5. **Read-only return** — when `readOnly` is true, render the `TextInput` component with all inputs passed through directly (full delegation).
+6. **Handlers** — build a test-id attribute from `testId`; the change handler updates `inputValue` from the event's input value; the blur handler commits the value via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+7. **Render** — same configuration as TextInput but with a `url` input type: full width, an outlined style, small size, current `inputValue`, the change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and the test-id attribute applied to the underlying input element.
 
 ## Behavioral Contract
 
-1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).
-2. **Sync from store:** `useEffect` watching `value` → `setInputValue(value)`.
+1. **Local state:** Maintain `inputValue` (string). Initialize from the `value` input (`''` default).
+2. **Sync from store:** A lifecycle effect watching `value` updates `inputValue`.
 3. **On change:** Update local state only.
-4. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, inputValue)`.
-5. **Input type:** Use `type='url'` for browser-native URL format hint/validation.
-6. **Read-only:** Delegate entirely to `TextInput`: `return <TextInput {...props} />`.
+4. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+5. **Input type:** Use a `url`-typed input for browser-native URL format hint/validation.
+6. **Read-only:** Delegate entirely to the `TextInput` component, passing all inputs through.
 
 ## Display Mode Rendering
 
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw URL string.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value` — raw URL string.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Delegate to `TextInput`: `return <TextInput {...props} />`.
+Delegate to `TextInput`, passing all inputs through.
 
 ## Visual Specifications
 
@@ -117,29 +70,27 @@ Identical to `TextInput` visually — no additional adornments.
 | Error state   | Red border + red helper text |
 | Helper text   | Below input                  |
 
-No special icon or adornment — the only difference from `TextInput` is `type='url'`.
+No special icon or adornment — the only difference from `TextInput` is the `url` input type.
 
 ## Edge Cases & Special Logic
 
-- The component is named `URLComponent` internally to avoid shadowing the global `URL` constructor. Register under the key `URL` in the component map.
-- `type='url'` triggers browser tooltip/validation but Pega validation is the authoritative source.
-- `onBlur` is only wired when `!readOnly`.
+- The component's export name should avoid shadowing the platform's global `URL` constructor. Register under the key `URL` in the project's component map.
+- The `url` input type triggers browser tooltip/validation but Pega validation is the authoritative source.
+- The blur handler is only wired when the field is not read-only.
 
 ## Dependencies
 
-- `handleEvent` from `../../helpers/event-utils`
-- `getComponentFromRegistry('TextInput')` — for read-only delegation
-- `getComponentFromRegistry('FieldValueList')` — for display modes
+- 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:** Single-line URL text input.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component      |
-| ------------------ | -------------------------- |
-| Default (CSS only) | `<input type="url">`       |
-| MUI                | `<TextField type='url' />` |
-| Ant Design         | `<Input type="url" />`     |
-| Chakra UI          | `<Input type="url" />`     |
+- **URL input** → use the DS's text input with input type set to `url`
+- **Read-only mode** → delegate to the `TextInput` component
+- **Error state** → the DS's error/danger visual state
+- **Helper text** → the DS's helper/description text slot below the input