@pega/sdk 0.0.4 → 0.0.5

package/templates/react-sdk-reference/.github/skills/design-system-extension-skills/FieldGroupList.md

@@ -1,113 +0,0 @@
-# Skill: FieldGroupList
-
-Repeating list of named field groups, each with its own children. Supports per-item delete and a global "+Add" link at the bottom.
-
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
-
----
-
-## Component Purpose
-
-Renders a vertical list of field group items. Each item has a bold name header, optional delete button (top-right), and rendered children (the group's fields). An optional "+Add" link appears at the bottom when adding is allowed. A horizontal divider separates items when `onAdd` is provided.
-
-## Pega Metadata
-
-- **Pega Name:** `FieldGroupList`
-- **Registration key:** `FieldGroupList` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives all data as direct props
-
-## Props
-
-| Prop       | Type                                                       | Required | Description                                                                                               |
-| ---------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
-| `items`    | `Array<{ name: string; id: string; children: ReactNode }>` | Yes      | List of field group items to render                                                                       |
-| `onDelete` | `(id: string) => void`                                     | No       | Called with the item's `id` when the delete button is clicked. If not provided, no delete button is shown |
-| `onAdd`    | `() => void`                                               | No       | Called when the "+Add" link is clicked. If not provided, no add link or dividers are shown                |
-
-## Behavioral Contract
-
-1. Render a `Grid container` with `spacing={4}` and `justifyContent='space-between'` as the outer wrapper.
-2. Inside, render a full-width inner Grid with `spacing={1}`.
-3. For **each item** in `props.items`:
-   - Render a full-width `Grid` keyed by `item.name`.
-   - Render `<b>{item.name}</b>` as the item header.
-   - If `onDelete` is provided, render a delete button:
-     - Floated right.
-     - `type='button'`, `id={'delete-row-' + item.id}`, `aria-label='Delete Row'`.
-     - Button class: `psdk-utility-button`.
-     - On click: call `onDelete(item.id)`.
-     - Button contains an `<img>` with the trash icon loaded via `Utils.getImageSrc('trash', Utils.getSDKStaticConentUrl())`.
-     - Image class: `psdk-utility-card-action-svg-icon`.
-   - Render `{item.children}`.
-   - Render `<br />`.
-   - If `onAdd` is provided: render `<Divider />`, then `<br />`.
-4. After all items, if `onAdd` is provided, render a `<Link>` (or `<a>`) with text `'+Add'`, `cursor: pointer`, and `onClick={onAdd}`.
-
-## Visual Specifications
-
-Derived from `FieldGroupList.tsx`:
-
-### Outer Layout
-
-| Property               | Value      |
-| ---------------------- | ---------- |
-| Grid container spacing | 4 (≈ 32px) |
-
-### Delete Button
-
-| Property    | Value                                                       |
-| ----------- | ----------------------------------------------------------- |
-| Float       | right                                                       |
-| Style class | `psdk-utility-button`                                       |
-| Icon source | `Utils.getImageSrc('trash', Utils.getSDKStaticConentUrl())` |
-
-### "+Add" Link
-
-| Property  | Value    |
-| --------- | -------- |
-| Cursor    | pointer  |
-| Underline | hover    |
-| Text      | `'+Add'` |
-
-**CSS-only implementation notes:**
-
-- Outer wrapper: `display: flex; flex-direction: column; gap: 32px`.
-- Item wrapper: `display: flex; flex-direction: column; gap: 8px; width: 100%`.
-- Item header row: `display: flex; justify-content: space-between; align-items: center`.
-- Delete button: `float: right` (or use flexbox `justify-content: space-between` on the header row instead).
-- Delete icon: `width: 20px; height: 20px` SVG image of a trash/delete icon.
-- Divider: `border-top: 1px solid var(--divider-color); margin: 8px 0`.
-- "+Add" link: `cursor: pointer; text-decoration: underline; color: var(--app-primary-color)`.
-
-## Edge Cases & Special Logic
-
-- If `items` is empty, render only the "+Add" link (if `onAdd` is provided).
-- If neither `onDelete` nor `onAdd` is provided, the list is read-only (no interactive elements).
-- The trash icon is loaded dynamically via `Utils.getImageSrc` — if this utility is unavailable, fall back to a standard `🗑` character or an SVG trash icon.
-- The delete button must use `type='button'` to prevent form submission.
-
-## Dependencies
-
-- `Utils` from `../../helpers/utils` — for `getImageSrc` and `getSDKStaticConentUrl` (used only for the trash icon)
-- No Pega SDK `getPConnect` imports required
-
-## Design System Mapping
-
-**UI control type:** Repeating list of named groups with optional delete and add actions.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                 |
-| ------------------ | --------------------------------------------------------------------- |
-| Default (CSS only) | Flex column layout with `<hr>` divider and `<button>` delete          |
-| MUI                | `<Grid container>` items with `<Divider>` and `<Link>` for "+Add"     |
-| Ant Design         | `<List>` items with `<Divider>` and `<Button type='link'>` for "+Add" |
-| Chakra UI          | `<VStack>` with `<Divider>` and `<Button variant='link'>`             |
-| Shadcn/ui          | `<div>` flex column with `<Separator>` and a link button              |
-
-When implementing in a specific design system, map the following:
-
-- Delete button → icon button or `danger` variant button placed at the item top-right
-- Divider between items → `<Divider>` / `<hr>` (only when `onAdd` is present)
-- "+Add" link → a text link / `Button variant='link'` that calls `onAdd`
-- Trash icon → design system's delete icon or an SVG

package/templates/react-sdk-reference/.github/skills/design-system-extension-skills/Operator.md

@@ -1,155 +0,0 @@
-# Skill: Operator
-
-Read-only display of a Pega case operator (creator or updater). Shows the operator's name and relative timestamp. On click, fetches full operator details from Pega and displays them in a popover.
-
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
-
----
-
-## Component Purpose
-
-Renders a clickable read-only field displaying a case operator's name and the relative time of their action (created/updated). Clicking the field triggers an async fetch of the operator's profile details (position, organization, reports-to, telephone, email) and shows them in a popover panel.
-
-## Pega Metadata
-
-- **Pega Name:** `Operator`
-- **Registration key:** `Operator` (in `component-map.ts`)
-- **Extends `PConnProps`** — but does NOT call `getPConnect()`. Props are all passed directly.
-
-## Props
-
-The component interface extends `PConnProps` but all rendering data is passed as explicit props:
-
-| Prop             | Type                                   | Required | Description                                                                                                                        |
-| ---------------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `label`          | `string`                               | Yes      | The field label used to identify which operator to display. Must be `'create operator'` or `'update operator'` (case-insensitive). |
-| `displayLabel`   | `any`                                  | No       | Alternative label (used if `label` doesn't match). Also compared case-insensitively.                                               |
-| `createDateTime` | `string`                               | Yes      | ISO datetime string of when the case was created                                                                                   |
-| `createLabel`    | `string`                               | Yes      | Display label for the create operator field                                                                                        |
-| `createOperator` | `{ userName: string; userId: string }` | Yes      | Creator's name and ID                                                                                                              |
-| `updateDateTime` | `string`                               | Yes      | ISO datetime string of last update                                                                                                 |
-| `updateLabel`    | `string`                               | Yes      | Display label for the update operator field                                                                                        |
-| `updateOperator` | `{ userName: string; userId: string }` | Yes      | Updater's name and ID                                                                                                              |
-
-## Behavioral Contract
-
-### 1. Operator Selection
-
-Determine which operator to display based on `label.toLowerCase()` or `displayLabel?.toLowerCase()`:
-
-- If either is `'create operator'`:
-  - `caseOpLabel = createLabel`
-  - `caseOpName = createOperator.userName`
-  - `caseOpId = createOperator.userId`
-  - `caseTime = createDateTime`
-- If either is `'update operator'`:
-  - `caseOpLabel = updateLabel`
-  - `caseOpName = updateOperator.userName`
-  - `caseOpId = updateOperator.userId`
-  - `caseTime = updateDateTime`
-- Otherwise: `caseOpLabel = '---'`, `caseOpName = '---'`, `caseOpId = ''`, `caseTime = ''`.
-
-### 2. Main Display
-
-Render a read-only TextField (standard variant, no underline, pointer cursor) with:
-
-- `defaultValue={caseOpName}`
-- `label={caseOpLabel}`
-- `onClick={showOperatorDetails}`
-- `readOnly: true`, `disableUnderline: true`, `cursor: 'pointer'`
-
-Below the TextField, render the relative time: `Utils.generateDateTime(caseTime, 'DateTime-Since')`.
-
-### 3. Popover on Click (`showOperatorDetails`)
-
-When the TextField is clicked:
-
-1. Call `PCore.getUserApi().getOperatorDetails(caseOpId)` — returns a Promise.
-2. Use `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` to localize field labels.
-3. On resolution, build a fields array with these entries (using `'---'` as fallback for missing values):
-   - Position (`pyPosition`)
-   - Organization (`pyOrganization`)
-   - Reports to (`pyReportToUserName`)
-   - Telephone (`pyTelephone`) — rendered as `<a href={'tel:' + value}>{value}</a>`
-   - Email address (`pyEmailAddress`) — rendered as `<a href={'mailto:' + value}>{value}</a>`
-4. If `res.data.pyOperatorInfo.pyUserName` is empty, use all `'---'` fallbacks.
-5. Set `popoverFields` state with the resolved fields.
-6. Set `popoverAnchorEl` to the clicked element to open the popover.
-
-### 4. Popover Layout
-
-The popover renders when `popoverAnchorEl` is set:
-
-- Anchor origin: `{ vertical: 'bottom', horizontal: 'center' }`
-- Transform origin: `{ vertical: 'top', horizontal: 'center' }`
-- Max width: `45ch`
-- Content: A `Grid container` with:
-  - `Typography h6` showing `caseOpName` at full width.
-  - One row per field: 6-col `Typography caption` (label) + 6-col `Typography subtitle2` (value).
-
-Closing the popover sets `popoverAnchorEl` to `null`.
-
-## Visual Specifications
-
-Derived from `Operator.tsx` makeStyles:
-
-### Root Container
-
-| Property | Value                      |
-| -------- | -------------------------- |
-| Padding  | `theme.spacing(1)` (≈ 8px) |
-| Margin   | `theme.spacing(1)`         |
-
-### Popover Container
-
-| Property  | Value              |
-| --------- | ------------------ |
-| Padding   | `theme.spacing(1)` |
-| Margin    | `theme.spacing(1)` |
-| Max width | 45ch               |
-
-**CSS-only implementation notes:**
-
-- Main display: read-only text field with label above, value below, pointer cursor on the value element.
-- Time display: secondary muted text below the operator name (e.g., `font-size: 0.75rem; color: var(--text-secondary)`).
-- Popover: `position: absolute; background: var(--bg-paper); border: 1px solid var(--divider); border-radius: 4px; padding: 8px; max-width: 45ch; box-shadow: 0 4px 12px rgba(0,0,0,0.15)`.
-- Operator name in popover: `font-size: 1.25rem; font-weight: 500; margin-bottom: 8px`.
-- Detail rows: `display: grid; grid-template-columns: 1fr 1fr; gap: 4px; align-items: baseline`.
-- Detail label: `font-size: 0.75rem; color: var(--text-secondary)`.
-- Detail value: `font-size: 0.875rem; font-weight: 500`.
-- Close popover on outside click (use `onClose` / blur handler).
-
-## Edge Cases & Special Logic
-
-- If `caseOpId` is empty (label not recognized), do NOT call `getOperatorDetails` — the fetch would fail.
-- If the API response has no `pyOperatorInfo.pyUserName`, fall back to all `'---'` for field values (still open the popover).
-- `Utils.generateDateTime(caseTime, 'DateTime-Since')` handles empty `caseTime` gracefully.
-- State: `popoverFields` starts as empty array `[]`. Check `popoverFields.length === 0` and return `undefined` from `getPopoverGrid()` to render nothing before data loads.
-
-## Dependencies
-
-- `Utils` from `../../helpers/utils` — `Utils.generateDateTime` for relative time display
-- `PCore.getUserApi().getOperatorDetails(userId)` — global Pega runtime API for operator details
-- `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` — for localized field labels in the popover
-
-## Design System Mapping
-
-**UI control type:** Clickable read-only field with async popover detail panel.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                           |
-| ------------------ | --------------------------------------------------------------- |
-| Default (CSS only) | `<div>` with click handler, custom CSS popover/tooltip panel    |
-| MUI                | Read-only `<TextField>` + `<Popover>` with `<Grid>` detail rows |
-| Ant Design         | `<Input readOnly>` + `<Popover>` with `<Descriptions>`          |
-| Chakra UI          | `<Input isReadOnly>` + `<Popover>` with custom content          |
-| Shadcn/ui          | `<Input readOnly>` + `<Popover>` + `<PopoverContent>`           |
-
-When implementing in a specific design system, map the following:
-
-- `onClick` on read-only input → trigger async fetch + open popover
-- `PCore.getUserApi().getOperatorDetails()` → call this before showing the popover
-- Popover anchor → position relative to the clicked element
-- `Utils.generateDateTime(caseTime, 'DateTime-Since')` → relative time display (e.g., "2 hours ago")
-- Telephone/email in popover → clickable `<a href='tel:...'>` and `<a href='mailto:...'>` links

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

@@ -1,295 +0,0 @@
-# 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.
-
----
-
-## 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)
-```
-
-Components are registered in `src/components/component-map.ts` and resolved at runtime via `getComponentFromRegistry` from `@pega/sdk-react`.
-
----
-
-## 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;
-}
-```
-
----
-
-## 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}
-    />
-  );
-}
-```
-
----
-
-## Design System Adaptation
-
-When filling in the `// [DS RENDER]` section with a specific design system:
-
-**1. Check the component-specific skill file** — `.github/skills/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.
-
-**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.
-
-**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:
-
-```bash
-find node_modules/<ds-package> -name "ComponentName.d.ts" | head -3
-grep -A 40 "interface.*Props" <path-to-file>
-```
-
-**4. Prop mapping conventions** — adapt these Pega/SDK props to whatever your 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                    |
-
-**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.
-
----
-
-## Event Handling
-
-Use `src/components/helpers/event-utils.ts` to commit values to the Pega store:
-
-```typescript
-import handleEvent from '../../helpers/event-utils';
-
-// Get references
-const actions = pConn.getActionsApi();
-const propName = (pConn.getStateProps() as any).value;
-
-// 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)
-```
-
-**Pattern:** Track local state with `useState`, update on user input, then call `handleEvent` on blur to commit.
-
----
-
-## Display Modes
-
-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'` |
-
-Use `getComponentFromRegistry('FieldValueList')` to get the display component.
-
----
-
-## 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');
-```
-
-This is used when:
-
-- Rendering display modes (FieldValueList)
-- Delegating to another field component (e.g., Date delegates to TextInput for readOnly)
-
----
-
-## 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
-}
-```
-
----
-
-## 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                                    |
-
----
-
-## 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`).