@pega/sdk 0.0.3 → 0.0.5

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

@@ -0,0 +1,145 @@
+# Skill: URL
+
+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.
+
+---
+
+## Component Purpose
+
+Renders a single-line text input of type `url`. Provides browser-native URL format validation. Delegates read-only rendering to the `TextInput` component.
+
+## Pega Metadata
+
+- **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" ... />;
+}
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).
+2. **Sync from store:** `useEffect` watching `value` → `setInputValue(value)`.
+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} />`.
+
+## 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' />`.
+
+## Read-Only Rendering
+
+Delegate to `TextInput`: `return <TextInput {...props} />`.
+
+## Visual Specifications
+
+Identical to `TextInput` visually — no additional adornments.
+
+| Property      | Value                        |
+| ------------- | ---------------------------- |
+| Width         | 100%                         |
+| Size          | Small (~40px height)         |
+| Variant       | Outlined                     |
+| Border        | 1px solid outlined           |
+| Border radius | 4px                          |
+| Error state   | Red border + red helper text |
+| Helper text   | Below input                  |
+
+No special icon or adornment — the only difference from `TextInput` is `type='url'`.
+
+## 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`.
+
+## Dependencies
+
+- `handleEvent` from `../../helpers/event-utils`
+- `getComponentFromRegistry('TextInput')` — for read-only delegation
+- `getComponentFromRegistry('FieldValueList')` — for display modes
+
+## Design System Mapping
+
+**UI control type:** Single-line URL text input.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component      |
+| ------------------ | -------------------------- |
+| Default (CSS only) | `<input type="url">`       |
+| MUI                | `<TextField type='url' />` |
+| Ant Design         | `<Input type="url" />`     |
+| Chakra UI          | `<Input type="url" />`     |

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

@@ -0,0 +1,293 @@
+# Skill: UserReference
+
+User picker field that renders as either a search box (AutoComplete) or a dropdown, populated from the Pega operators data page.
+
+> **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 user selection field. Can display as a typeahead search box or a dropdown list of Pega users. Resolves user IDs to display names for read-only and display modes. Optimized with shallow comparison to avoid unnecessary re-renders.
+
+## Pega Metadata
+
+- **Pega Name:** `UserReference`
+- **Type / Subtype:** `Field` / `Text-UserReference`
+- **Registration key:** `UserReference` (in `component-map.ts`)
+
+## Props (component-specific)
+
+> Extends `PConnProps` (NOT `PConnFieldProps` — field-specific props are defined manually):
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+```
+
+| Prop                  | Type                 | Default    | Description                                                      |
+| --------------------- | -------------------- | ---------- | ---------------------------------------------------------------- |
+| `displayAs`           | `string` (optional)  | `''`       | `'Drop-down list'` or `'Search box'` — determines the input type |
+| `displayMode`         | `string` (optional)  | `''`       | `'DISPLAY_ONLY'` or `'STACKED_LARGE_VAL'`                        |
+| `label`               | `string` (optional)  | `''`       | Field label                                                      |
+| `value`               | `any` (optional)     | `''`       | Raw value from Pega store (may be a user object or string ID)    |
+| `testId`              | `string` (optional)  | `''`       | Test identifier                                                  |
+| `placeholder`         | `string` (optional)  | `''`       | Placeholder text                                                 |
+| `helperText`          | `string` (optional)  | `''`       | Helper text                                                      |
+| `disabled`            | `boolean` (optional) | `false`    |                                                                  |
+| `readOnly`            | `boolean` (optional) | `false`    |                                                                  |
+| `required`            | `boolean` (optional) | `false`    |                                                                  |
+| `validatemessage`     | `string` (optional)  | `''`       | Validation error message                                         |
+| `showAsFormattedText` | `boolean` (optional) | `false`    | When `true` in read-only mode, show formatted user name text     |
+| `additionalProps`     | `object` (optional)  | `{}`       | Extra props forwarded to the child component                     |
+| `hideLabel`           | `boolean` (optional) | `false`    |                                                                  |
+| `variant`             | `string` (optional)  | `'inline'` | Layout variant                                                   |
+| `onChange`            | `any` (optional)     | —          | Change handler (passed through to child)                         |
+
+## Component Skeleton
+
+Orchestrator component — renders either AutoComplete, Dropdown, formatted text, or FieldValueList based on mode. Uses `memo` with custom comparison.
+
+```typescript
+import { memo, useEffect, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+import { getUserId, isUserNameAvailable } from './UserReferenceUtils';
+
+const DROPDOWN_LIST = 'Drop-down list';
+const SEARCH_BOX = 'Search box';
+
+interface UserReferenceProps extends PConnProps {
+  displayAs?: string;
+  displayMode?: string;
+  label?: string;
+  value?: any;
+  testId?: string;
+  placeholder?: string;
+  helperText?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  validatemessage?: string;
+  showAsFormattedText?: boolean;
+  additionalProps?: object;
+  hideLabel?: boolean;
+  variant?: string;
+  onChange?: any;
+}
+
+const UserReference = (props: UserReferenceProps) => {
+  // 1. Registry lookups
+  const AutoComplete = getComponentFromRegistry('AutoComplete');
+  const Dropdown = getComponentFromRegistry('Dropdown');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props (all with defaults)
+  const {
+    label = '',
+    displayAs = '',
+    displayMode = '',
+    getPConnect,
+    value = '',
+    testId = '',
+    helperText = '',
+    validatemessage = '',
+    placeholder = '',
+    showAsFormattedText = false,
+    additionalProps = {},
+    hideLabel = false,
+    readOnly = false,
+    required = false,
+    disabled = false,
+    onChange,
+  } = props;
+
+  // 3. State
+  const [dropDownDataSource, setDropDownDataSource] = useState([]);
+  const [userName, setUserName] = useState('');
+
+  // 4. Derived
+  const OPERATORS_DP = PCore.getEnvironmentInfo().getDefaultOperatorDP();
+  const userId = getUserId(value);
+
+  // 5. useEffect — deps: [displayAs, readOnly, showAsFormattedText, value]
+  //    Case 1: userId && readOnly && showAsFormattedText → resolve userName
+  //    Case 2: displayAs === DROPDOWN_LIST → fetch user list via REST
+
+  // 6. Rendering decision tree
+  //    displayMode DISPLAY_ONLY → FieldValueList(userName || '')
+  //    displayMode STACKED → FieldValueList(userName || '', variant='stacked')
+  //    readOnly && showAsFormattedText && userId → label + userName text
+  //    displayAs SEARCH_BOX → <AutoComplete datasource={OPERATORS_DP} listType='datapage' ...>
+  //    displayAs DROPDOWN_LIST → <Dropdown datasource={dropDownDataSource} listType='associated' ...>
+  return userReferenceComponent;
+};
+
+// 7. Memo with custom comparison
+const comparisonFn = (prevProps, nextProps) =>
+  getUserId(prevProps.value) === getUserId(nextProps.value) &&
+  prevProps.validatemessage === nextProps.validatemessage &&
+  prevProps.required === nextProps.required &&
+  prevProps.disabled === nextProps.disabled &&
+  prevProps.readOnly === nextProps.readOnly;
+
+export default memo(UserReference, comparisonFn);
+```
+
+## Behavioral Contract
+
+### User ID extraction
+
+`getUserId(value)` — utility that extracts the user identifier from the value (which may be a plain string or a user object with an ID property).
+
+### State
+
+- `dropDownDataSource` (array): populated when `displayAs === 'Drop-down list'`
+- `userName` (string): resolved display name for formatted text mode
+
+### Mount effect: `useEffect([displayAs, readOnly, showAsFormattedText, value])`
+
+**Case 1: `userId && readOnly && showAsFormattedText`**
+
+- If `isUserNameAvailable(value)`: `setUserName(value.userName)` — username already in value object
+- Else: call `PCore.getUserApi().getOperatorDetails(userId)` and extract `pyUserName` from response
+
+**Case 2: `displayAs === 'Drop-down list'`**
+
+- Call `PCore.getRestClient().invokeRestApi('getListData', { queryPayload: { dataViewName: OPERATORS_DP } })`
+- Map results to `{key: pyUserIdentifier, value: pyUserName}` array
+- `setDropDownDataSource(mapped)`
+
+`OPERATORS_DP = PCore.getEnvironmentInfo().getDefaultOperatorDP()` — the default operators data page name.
+
+### Rendering decision tree
+
+```
+if displayMode === 'DISPLAY_ONLY' → FieldValueList(userName || '')
+if displayMode === 'STACKED_LARGE_VAL' → FieldValueList(userName || '', variant='stacked')
+if readOnly && showAsFormattedText && userId → formatted text label+body
+else if displayAs === 'Search box' → AutoComplete component
+else if displayAs === 'Drop-down list' → Dropdown component
+```
+
+### Subsection: Search box mode (`displayAs === 'Search box'`)
+
+Render `AutoComplete` with hardcoded columns for operator search:
+
+```typescript
+columns = [
+  { value: 'pyUserName', display: 'true', useForSearch: true, primary: 'true' },
+  {
+    value: 'pyUserIdentifier',
+    setProperty: 'Associated property',
+    key: 'true',
+    display: 'true',
+    secondary: 'true',
+    useForSearch: 'true',
+  },
+];
+```
+
+Props: `datasource={OPERATORS_DP}`, `listType='datapage'`, `value={userId}`, plus label/placeholder/readOnly/disabled/required/helperText/validatemessage/hideLabel/onChange/additionalProps/testId.
+
+### Subsection: Dropdown mode (`displayAs === 'Drop-down list'`)
+
+Render `Dropdown` with:
+
+- `datasource={dropDownDataSource}` (fetched user list)
+- `listType='associated'`
+- `value={userId}`
+- Plus same field props as above
+
+### Subsection: Formatted text read-only (`readOnly && showAsFormattedText && userId`)
+
+Render a label + name display:
+
+```html
+<div>
+  <caption-text>{label}</caption-text>
+  <body-text>{userName}</body-text>
+</div>
+```
+
+### Re-render optimization
+
+Export with `memo` using custom comparison `comparisonFn`:
+
+```typescript
+const comparisonFn = (prevProps, nextProps) =>
+  getUserId(prevProps.value) === getUserId(nextProps.value) &&
+  prevProps.validatemessage === nextProps.validatemessage &&
+  prevProps.required === nextProps.required &&
+  prevProps.disabled === nextProps.disabled &&
+  prevProps.readOnly === nextProps.readOnly;
+```
+
+`export default memo(UserReference, comparisonFn)`
+
+## Display Mode Rendering
+
+Uses resolved `userName` (not raw `value`):
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={userName || ''} />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={userName || ''} variant='stacked' />`
+
+`userName` may still be empty string while the async `getOperatorDetails` call resolves — this is expected.
+
+## Visual Specifications
+
+The visual appearance is determined by the child component rendered:
+
+- **Search box**: Same as `AutoComplete` — combobox input with outlined border, floating label
+- **Dropdown**: Same as `Dropdown` — select field with outlined border, floating label
+- **Formatted text read-only**:
+
+| Property | Value                                                     |
+| -------- | --------------------------------------------------------- |
+| Label    | Caption-size text (small, secondary color) above the name |
+| Name     | Body text (normal size)                                   |
+| Spacing  | Standard form field spacing                               |
+
+**CSS-only for formatted text:**
+
+```css
+.user-reference-label {
+  font-size: 0.75rem;
+  color: rgba(0, 0, 0, 0.6);
+  margin-bottom: 4px;
+}
+.user-reference-name {
+  font-size: 1rem;
+}
+```
+
+## Edge Cases & Special Logic
+
+- **`getUserId`**: handles both plain string values and object values with an ID property.
+- **`isUserNameAvailable`**: checks whether the value object already contains a `userName` property (avoiding unnecessary API call).
+- **Async name resolution**: when `userName` is not available in the value object, a REST call is made. The component renders empty initially and updates when the call completes.
+- **Drop-down source**: Users are fetched via REST API (`getListData`), not via a data page config — this is different from `AutoComplete`/`Dropdown` field patterns.
+- **`onChange` prop** is passed through to the child component unchanged — it's the platform-wired handler.
+
+## Dependencies
+
+- `memo` from React.
+- `getUserId`, `isUserNameAvailable` from `./UserReferenceUtils` (local utility).
+- `getComponentFromRegistry('AutoComplete')` — for search box mode.
+- `getComponentFromRegistry('Dropdown')` — for dropdown mode.
+- `getComponentFromRegistry('FieldValueList')` — for display modes.
+- `PCore.getUserApi().getOperatorDetails()` — for async user name resolution.
+- `PCore.getRestClient().invokeRestApi('getListData', ...)` — for dropdown data source.
+- `PCore.getEnvironmentInfo().getDefaultOperatorDP()` — for operators data page name.
+
+## Design System Mapping
+
+**UI control type:** User picker — delegates to AutoComplete or Dropdown for the actual input.
+
+Listed design systems are examples only.
+
+| Mode                     | Underlying control                |
+| ------------------------ | --------------------------------- |
+| Search box               | AutoComplete (combobox/typeahead) |
+| Drop-down list           | Dropdown (select)                 |
+| Formatted text read-only | Label + text display              |
+| Display mode             | FieldValueList                    |

package/templates/react-sdk-reference/.ai-common/skills/run-and-verify.md

@@ -0,0 +1,70 @@
+# Skill: Run and Verify
+
+Build the application, run the dev server, and verify changes work correctly.
+
+---
+
+## Build Verification
+
+### If inside the pega-sdk monorepo:
+
+```bash
+# Full build (all packages + samples)
+cd /path/to/pega-sdk
+npm run build
+
+# Force rebuild sdk-react (if you modified it)
+npx nx run sdk-react:build --skip-nx-cache
+```
+
+### If standalone repo:
+
+```bash
+npm run build
+```
+
+### What to check:
+
+- Zero TypeScript errors
+- Zero build warnings related to missing imports
+- Output bundle is generated
+
+---
+
+## Dev Server
+
+```bash
+npm run dev
+# Opens on http://localhost:3500
+```
+
+### What to verify:
+
+1. App loads without console errors
+2. "Create Case" button appears after auth
+3. Clicking "Create Case" renders the form
+4. Field inputs accept keyboard input
+5. Tabbing between fields triggers blur (values persist)
+6. Validation errors appear when required fields are empty
+7. Form submission works (assignment completes)
+
+---
+
+## Common Issues
+
+| Symptom                                      | Cause                                     | Fix                                                                                 |
+| -------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------- |
+| "X is not registered" console error          | Component missing from `component-map.ts` | Add the import + map entry                                                          |
+| Field value doesn't persist after blur       | `handleEvent` not called on blur          | Add `onBlur` handler calling `handleEvent(actions, 'changeNblur', propName, value)` |
+| Read-only view shows nothing                 | Missing `displayMode` handling            | Add the `DISPLAY_ONLY` / `STACKED_LARGE_VAL` checks                                 |
+| TypeScript error on `getPConnect`            | Wrong props interface                     | Extend `PConnFieldProps` or `PConnProps` from `@pega/sdk-react`                     |
+| Build fails on CSS import                    | Missing CSS loader config                 | Ensure Vite config handles `.css` imports                                           |
+| "Cannot read property of undefined" on theme | Design system provider missing            | Wrap app in the design system's ThemeProvider/Provider                              |
+
+---
+
+## Quick Lint Check
+
+```bash
+npx tsc --noEmit   # TypeScript only, no output
+```