@pega/sdk 0.0.5 → 0.0.6

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

@@ -1,219 +1,115 @@
 # Skill: Field Components
 
-Create or replace field components (form inputs) in the react-sdk-reference application. Field components render individual form controls that bind to Pega case properties.
+Create or replace field components (form inputs) in the project. Field components render individual form controls that bind to Pega case properties.
 
 ---
 
 ## Architecture Overview
 
-```
-src/components/field/<ComponentName>/
-├── <ComponentName>.tsx      # Component implementation
-├── index.tsx                # Re-export: export { default } from './<ComponentName>'
-└── config-ext.json          # Metadata (name, label, description, type, subtype)
-```
+Each field component lives in its own folder under the project's field components directory, named after the component. The folder contains:
 
-Components are registered in `src/components/component-map.ts` and resolved at runtime via `getComponentFromRegistry` from `@pega/sdk-react`.
+| File                         | Purpose                                                         |
+| ---------------------------- | --------------------------------------------------------------- |
+| Component implementation     | The component's logic and markup                                |
+| Re-export module             | Re-exports the component as the folder's default export         |
+| Metadata (`config-ext.json`) | Registration metadata (name, label, description, type, subtype) |
+
+Components are registered in the project's component map and resolved at runtime via the project's component registry.
 
 ---
 
-## Props Interface
-
-All field components extend `PConnFieldProps` from `src/types/PConnProps.d.ts`:
-
-```typescript
-import type { PConnFieldProps } from '../../../types/PConnProps';
-
-interface PConnFieldProps extends PConnProps {
-  label: string; // Field label text
-  required: boolean; // Whether the field is required
-  disabled: boolean; // Whether the field is disabled
-  value?: string; // Current field value from the store
-  validatemessage: string; // Validation error message
-  status?: string; // 'error' | 'warning' | undefined
-  onChange: any; // Change handler (wired by platform)
-  onBlur?: any; // Blur handler (wired by platform)
-  readOnly: boolean; // Whether the field is read-only
-  testId: string; // Test identifier for automation
-  helperText: string; // Helper/hint text below the field
-  displayMode?: string; // 'DISPLAY_ONLY' | 'STACKED_LARGE_VAL' | undefined
-  hideLabel: boolean; // Whether to hide the label
-  placeholder?: string; // Placeholder text
-}
-
-interface PConnProps {
-  getPConnect: () => typeof PConnect; // Returns the PConnect API object
-}
-```
-
-Extend `PConnFieldProps` for component-specific additional props:
-
-```typescript
-interface MyFieldProps extends PConnFieldProps {
-  fieldMetadata?: any;
-  maxLength?: number;
-}
-```
+## Input Contract
+
+All field components extend the project's **field input contract**. The field input contract itself extends a **base component interface**, which provides a single `getPConnect` accessor function (returns the PConnect API object).
+
+The field input contract defines these fields:
+
+| Field             | Type                | Description                                            |
+| ----------------- | ------------------- | ------------------------------------------------------ |
+| `label`           | `string`            | Field label text                                       |
+| `required`        | `boolean`           | Whether the field is required                          |
+| `disabled`        | `boolean`           | Whether the field is disabled                          |
+| `value`           | `string` (optional) | Current field value from the store                     |
+| `validatemessage` | `string`            | Validation error message                               |
+| `status`          | `string` (optional) | `'error'` \| `'warning'` \| undefined                  |
+| `onChange`        | `any`               | Change handler (wired by platform)                     |
+| `onBlur`          | `any` (optional)    | Blur handler (wired by platform)                       |
+| `readOnly`        | `boolean`           | Whether the field is read-only                         |
+| `testId`          | `string`            | Test identifier for automation                         |
+| `helperText`      | `string`            | Helper/hint text below the field                       |
+| `displayMode`     | `string` (optional) | `'DISPLAY_ONLY'` \| `'STACKED_LARGE_VAL'` \| undefined |
+| `hideLabel`       | `boolean`           | Whether to hide the label                              |
+| `placeholder`     | `string` (optional) | Placeholder text                                       |
+
+Extend the field input contract for component-specific additional inputs (e.g., a component that needs `fieldMetadata` and `maxLength` would extend the field input contract with those two additional optional fields).
 
 ---
 
 ## Implementation Pattern
 
-### Abstract Field Component Template
-
-This template is design-system agnostic. It defines the **behavioral skeleton** every field component must follow. Replace the `// [DS RENDER]` section with your design system's input primitive — see the "Design System Adaptation" section below for guidance.
-
-```typescript
-import { useState, useEffect } from 'react';
-// Import your design system component here:
-// e.g. import { Input } from 'antd';
-// e.g. import { Input } from '@chakra-ui/react';
-
-import handleEvent from '../../helpers/event-utils';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface MyFieldProps extends PConnFieldProps {
-  // Add component-specific props here
-}
-
-export default function MyField(props: MyFieldProps) {
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  const {
-    getPConnect,
-    label,
-    required,
-    disabled,
-    value = '',
-    validatemessage,
-    status,
-    readOnly,
-    testId,
-    helperText,
-    displayMode,
-    hideLabel,
-    placeholder
-  } = props;
-
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-  const helperTextToDisplay = validatemessage || helperText;
-
-  // 1. Track input value locally — do NOT commit on every keystroke
-  const [inputValue, setInputValue] = useState(value);
-
-  // 2. Sync local state when the store value changes
-  useEffect(() => {
-    setInputValue(value);
-  }, [value]);
-
-  // 3. Display modes — must short-circuit before any interactive rendering
-  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. Event handlers
-  function handleChange(newValue: string) {
-    setInputValue(newValue); // update local state only
-  }
-
-  function handleBlur() {
-    handleEvent(actions, 'changeNblur', propName, inputValue); // commit to Pega store
-  }
-
-  // 5. [DS RENDER] — replace with your design system's input primitive
-  // Refer to "Design System Adaptation" below for prop mapping guidance
-  return (
-    <YourDesignSystemInput
-      value={inputValue}
-      onChange={handleChange}
-      onBlur={!readOnly ? handleBlur : undefined}
-      disabled={disabled}
-      readOnly={readOnly}
-      required={required}
-      placeholder={placeholder}
-      label={label}
-      helperText={helperTextToDisplay}
-      isInvalid={status === 'error'}
-      data-test-id={testId}
-    />
-  );
-}
-```
+### Abstract Field Component Pattern
+
+This pattern is design-system agnostic. It defines the **behavioral skeleton** every field component must follow. The final render step must be adapted to your design system's input primitive — see the "Design System Adaptation" section below for guidance.
+
+**Module Setup:** The component depends on the project's event-commit utility (for committing value changes to the Pega store) and the project's component registry (for resolving the display-mode renderer). Define the input contract as an extension of the project's field input contract with any component-specific additional inputs. Export the component as the module's default export.
+
+**Main Component Logic** — the component follows these steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry to get the display-mode renderer.
+2. **Receive inputs** — extract `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`, plus any component-specific inputs.
+3. **PConnect setup** — call `getPConnect()` to get `pConn`; get `actions` via `pConn.getActionsApi()`; get `propName` via `(pConn.getStateProps() as any).value`; compute `helperTextToDisplay = validatemessage || helperText`.
+4. **Track input value locally** — maintain local state initialized to `value`. Do NOT commit to the store on every keystroke.
+5. **Sync local state from the store** — use a lifecycle effect watching `value` to update the local state whenever the store value changes.
+6. **Display mode short-circuits** — these must be checked before any interactive rendering:
+   - If `displayMode === 'DISPLAY_ONLY'`: return `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value`.
+   - If `displayMode === 'STACKED_LARGE_VAL'`: return the same but with a stacked layout variant.
+7. **Event handlers:**
+   - The change handler — updates local state only (no store commit).
+   - The blur handler — invokes the project's event-commit utility with event type `'changeNblur'`, the property name, and the local value to commit to the Pega store.
+8. **Render** — render the design system's input primitive with these inputs wired: `value` (local state), the change handler, the blur handler (only when not read-only), `disabled`, `readOnly`, `required`, `placeholder`, `label`, `helperText` (the computed display text), an error/invalid flag driven by `status === 'error'`, and a test-id attribute driven by `testId`.
 
 ---
 
 ## Design System Adaptation
 
-When filling in the `// [DS RENDER]` section with a specific design system:
-
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/field-skills/<ComponentName>.md` contains a **Design System Mapping** table that lists the recommended DS component for common design systems. Use it as a starting point.
+When implementing the render section with a specific design system:
 
-**2. If the chosen design system is not in the mapping table** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/field-skills/<ComponentName>.md` contains a **Design System Mapping** section that describes how to map the component's behavior to a DS primitive. Use it as a starting point.
 
-**3. Discover the API from installed packages** — before writing any render JSX, confirm all prop names from `.d.ts` files. Never rely on training-knowledge of a DS API:
+**2. If the chosen design system is not covered** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
 
-```bash
-find node_modules/<ds-package> -name "ComponentName.d.ts" | head -3
-grep -A 40 "interface.*Props" <path-to-file>
-```
+**3. Discover the API from installed packages** — before writing the render markup, confirm all input names from the design system's type declarations. Never rely on training-knowledge of a DS API. Search the design system package's type declaration files for the target component name, then read the exported input interface to confirm exact input names and types.
 
-**4. Prop mapping conventions** — adapt these Pega/SDK props to whatever your DS component calls them:
+**4. Input mapping conventions** — adapt these Pega/SDK inputs to whatever the DS component calls them:
 
-| Pega/SDK prop                     | Meaning                       | Typical DS equivalent                              |
-| --------------------------------- | ----------------------------- | -------------------------------------------------- |
-| `status === 'error'`              | Validation error state        | `error`, `status="error"`, `invalid`, `isInvalid`  |
-| `validatemessage \|\| helperText` | Helper/error text below field | `helperText`, `description`, `hint`, `extra`       |
-| `readOnly`                        | Non-editable, still visible   | `readOnly`, `isReadOnly`, `variant="borderless"`   |
-| `testId`                          | Automation selector           | `data-test-id` on the underlying `<input>` element |
-| `required`                        | Required field marker         | `required`, `isRequired`                           |
-| `hideLabel`                       | Suppress label display        | Pass empty string `''` as label                    |
+| Pega/SDK input                    | Meaning                       | Typical DS equivalent                               |
+| --------------------------------- | ----------------------------- | --------------------------------------------------- |
+| `status === 'error'`              | Validation error state        | `error`, `status="error"`, `invalid`, `isInvalid`   |
+| `validatemessage \|\| helperText` | Helper/error text below field | `helperText`, `description`, `hint`, `extra`        |
+| `readOnly`                        | Non-editable, still visible   | `readOnly`, `isReadOnly`, `variant="borderless"`    |
+| `testId`                          | Automation selector           | A test-id attribute on the underlying input element |
+| `required`                        | Required field marker         | `required`, `isRequired`                            |
+| `hideLabel`                       | Suppress label display        | Pass empty string `''` as label                     |
 
-**5. Use a form layout wrapper** — if the DS provides a wrapper that combines label + input + helper text (e.g., `<Form.Item>` in Ant Design, `<FormControl>` in Chakra UI), use it rather than composing them manually.
+**5. Use a form layout wrapper** — if the DS provides a wrapper that combines label + input + helper text (e.g., a form-item or form-control component), use it rather than composing them manually.
 
 ---
 
 ## Event Handling
 
-> ⚠️ **CRITICAL — DO NOT DUPLICATE IMPORTS FROM `field-utils`**
+> ⚠️ **CRITICAL — DO NOT DUPLICATE IMPORTS FROM FIELD UTILITIES**
 >
-> If the project has a `field-utils.ts` or `field-utils.tsx` file that exports utility functions AND types (e.g., `DynamicFieldProps`, `commitField`, `FieldValue`, `getFieldContext`, `useFieldValue`, `helperText`, `getOptions`), import everything you need in a **single import statement**.
+> If the project has a field-utilities module that exports utility functions AND types (e.g., field input types, commit helpers, value getters, context helpers, option-list helpers), import everything you need in a **single import statement**. NEVER add a separate type-only import for a symbol that is already imported from the same module — doing so causes a duplicate identifier error.
 >
-> ```typescript
-> // ✅ CORRECT — one import for both types and functions
-> import { commitField, DynamicFieldProps, FieldValue, getFieldContext, helperText } from '../field-utils';
->
-> // ❌ WRONG — duplicate identifier error!
-> import type { DynamicFieldProps } from '../field-utils';
-> import { commitField, DynamicFieldProps, FieldValue, getFieldContext } from '../field-utils';
-> ```
->
-> TypeScript allows mixing type and value exports in a single import. NEVER add a separate `import type` line for a symbol that is already imported in another import from the same module.
->
-> **Before writing imports:** Check what `field-utils` exports. If it exports `DynamicFieldProps` as a `type`, you can import it alongside value exports in one statement.
-
-Use `src/components/helpers/event-utils.ts` to commit values to the Pega store:
-
-```typescript
-import handleEvent from '../../helpers/event-utils';
+> **Before writing imports:** Check what the field-utilities module exports. If it exports a type, you can import it alongside value exports in one statement.
 
-// Get references
-const actions = pConn.getActionsApi();
-const propName = (pConn.getStateProps() as any).value;
+Use the project's event-commit utility to commit values to the Pega store. Obtain the two references it needs: `actions` via `pConn.getActionsApi()` and `propName` via `(pConn.getStateProps() as any).value`. Then invoke the utility with one of three event types:
 
-// Options:
-handleEvent(actions, 'change', propName, value); // Update store only
-handleEvent(actions, 'blur', propName, value); // Trigger validation only
-handleEvent(actions, 'changeNblur', propName, value); // Update + validate (most common)
-```
+- `'change'` — update store only.
+- `'blur'` — trigger validation only.
+- `'changeNblur'` — update and validate (most common).
 
-**Pattern:** Track local state with `useState`, update on user input, then call `handleEvent` on blur to commit.
+**Pattern:** Track local state, update on user input, then call the event-commit utility on blur to commit.
 
 ---
 
@@ -221,26 +117,19 @@ handleEvent(actions, 'changeNblur', propName, value); // Update + validate (most
 
 Every field component MUST handle these `displayMode` values:
 
-| Mode                  | Behavior                                                       |
-| --------------------- | -------------------------------------------------------------- |
-| `undefined` / `null`  | Render editable form control                                   |
-| `'DISPLAY_ONLY'`      | Render read-only via `FieldValueList` (inline layout)          |
-| `'STACKED_LARGE_VAL'` | Render read-only via `FieldValueList` with `variant='stacked'` |
+| Mode                  | Behavior                                                            |
+| --------------------- | ------------------------------------------------------------------- |
+| `undefined` / `null`  | Render editable form control                                        |
+| `'DISPLAY_ONLY'`      | Render read-only via `FieldValueList` (inline layout)               |
+| `'STACKED_LARGE_VAL'` | Render read-only via `FieldValueList` with a stacked layout variant |
 
-Use `getComponentFromRegistry('FieldValueList')` to get the display component.
+Resolve the `FieldValueList` component via the project's component registry.
 
 ---
 
 ## Resolving Other Components
 
-Use `getComponentFromRegistry` from `@pega/sdk-react` to resolve components by name:
-
-```typescript
-import { getComponentFromRegistry } from '@pega/sdk-react';
-
-const FieldValueList = getComponentFromRegistry('FieldValueList');
-const TextInput = getComponentFromRegistry('TextInput');
-```
+Use the project's component registry to resolve components by name at runtime — for example, resolving `'FieldValueList'` or `'TextInput'` returns the currently-registered component for that name (including any override).
 
 This is used when:
 
@@ -251,62 +140,51 @@ This is used when:
 
 ## Registration
 
-After creating a component, register it in `src/components/component-map.ts`:
-
-```typescript
-import MyField from './field/MyField';
-
-// In the getSampleComponentMap() return object:
-{
-  ...sdkComponents,
-  // ... other fields ...
-  MyField,      // Key must match the Pega component name exactly
-}
-```
+After creating a component, register it in the project's component map: import the component's default export from its folder under the field components directory, then add it to the object returned by the project's component registration function. The key used must match the Pega component name exactly.
 
 ---
 
 ## Existing Field Components
 
-| Component       | Pega Name       | Description                                    |
-| --------------- | --------------- | ---------------------------------------------- |
-| AutoComplete    | AutoComplete    | Typeahead search field                         |
-| CancelAlert     | CancelAlert     | Cancel confirmation dialog                     |
-| Checkbox        | Checkbox        | Single checkbox with label                     |
-| Currency        | Currency        | Currency input with formatting                 |
-| Date            | Date            | Date picker (uses @mui/x-date-pickers + dayjs) |
-| DateTime        | DateTime        | Date + time picker                             |
-| Decimal         | Decimal         | Decimal number input                           |
-| Dropdown        | Dropdown        | Select/dropdown with options from data page    |
-| Email           | Email           | Email input with icon                          |
-| Group           | Group           | Field group container                          |
-| Integer         | Integer         | Integer-only input                             |
-| Location        | Location        | Google Maps location picker                    |
-| Multiselect     | Multiselect     | Multi-select dropdown                          |
-| ObjectReference | ObjectReference | Reference to another object                    |
-| Percentage      | Percentage      | Percentage input                               |
-| Phone           | Phone           | Phone input (uses mui-tel-input)               |
-| RadioButtons    | RadioButtons    | Radio button group                             |
-| RichText        | RichText        | Rich text editor (TinyMCE)                     |
-| ScalarList      | ScalarList      | List of scalar values                          |
-| SelectableCard  | SelectableCard  | Card-style selection                           |
-| SemanticLink    | SemanticLink    | Clickable link to another case/object          |
-| TextArea        | TextArea        | Multi-line text input                          |
-| TextContent     | TextContent     | Static text display                            |
-| TextInput       | TextInput       | Single-line text input                         |
-| Time            | Time            | Time picker                                    |
-| URL             | URL             | URL input with validation                      |
-| UserReference   | UserReference   | User picker                                    |
+| Component       | Pega Name       | Description                       |
+| --------------- | --------------- | --------------------------------- |
+| AutoComplete    | AutoComplete    | Typeahead search field            |
+| CancelAlert     | CancelAlert     | Cancel confirmation dialog        |
+| Checkbox        | Checkbox        | Single checkbox with label        |
+| Currency        | Currency        | Currency input with formatting    |
+| Date            | Date            | Date picker                       |
+| DateTime        | DateTime        | Date + time picker                |
+| Decimal         | Decimal         | Decimal number input              |
+| Dropdown        | Dropdown        | Select/dropdown with options      |
+| Email           | Email           | Email input with icon             |
+| Group           | Group           | Field group container             |
+| Integer         | Integer         | Integer-only input                |
+| Location        | Location        | Google Maps location picker       |
+| Multiselect     | Multiselect     | Multi-select dropdown             |
+| ObjectReference | ObjectReference | Reference to another object       |
+| Percentage      | Percentage      | Percentage input                  |
+| Phone           | Phone           | Phone input with country selector |
+| RadioButtons    | RadioButtons    | Radio button group                |
+| RichText        | RichText        | Rich text editor                  |
+| ScalarList      | ScalarList      | List of scalar values             |
+| SelectableCard  | SelectableCard  | Card-style selection              |
+| SemanticLink    | SemanticLink    | Clickable link to another case    |
+| TextArea        | TextArea        | Multi-line text input             |
+| TextContent     | TextContent     | Static text display               |
+| TextInput       | TextInput       | Single-line text input            |
+| Time            | Time            | Time picker                       |
+| URL             | URL             | URL input with validation         |
+| UserReference   | UserReference   | User picker                       |
 
 ---
 
 ## Key Conventions
 
-1. **Default export** — Each component uses `export default function`.
-2. **index.tsx** — Re-exports: `export { default } from './ComponentName'`.
-3. **Local state** — Track input value locally, sync from `value` prop via `useEffect`.
-4. **Commit on blur** — Use `handleEvent(actions, 'changeNblur', propName, localValue)` on blur, not on every keystroke.
-5. **Error display** — Show `validatemessage` or `helperText` below the field; set `error={status === 'error'}`.
-6. **Read-only** — Set `readOnly` on input props or render a display-only component.
-7. **Test IDs** — Pass `data-test-id={testId}` to the underlying input element.
-8. **No PCore imports** — Access PCore globals directly (they're declared globally by `@pega/pcore-pconnect-typedefs`).
+1. **Default export** — Each component is exported as the module's default export.
+2. **Re-export module** — A re-export file in the folder exports the component as the folder's default.
+3. **Local state** — Track input value locally, sync from the `value` input via a lifecycle effect.
+4. **Commit on blur** — Use the project's event-commit utility with event type `'changeNblur'` on blur, not on every keystroke.
+5. **Error display** — Show `validatemessage` or `helperText` below the field; apply an error visual state when `status === 'error'`.
+6. **Read-only** — Set the read-only attribute on the input element or render a display-only component.
+7. **Test IDs** — Pass a test-id attribute driven by `testId` to the underlying input element.
+8. **No PCore imports** — Access PCore globals directly (they're declared globally by the Pega runtime type definitions).