@pega/sdk 0.0.3 → 0.0.5

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

@@ -1,8 +1,3 @@
----
-description: Field component skill: Group
-alwaysApply: false
----
-
 # Skill: Group
 
 Field group container that wraps child fields in a collapsible section with an optional heading and instructions.
@@ -23,17 +18,68 @@ A layout/structural component (not a form input). Wraps a set of child field com
 
 ## Props (component-specific)
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `children` | `ReactElement[]` | Child field components to render inside the group |
-| `heading` | `string` | The group heading/title |
-| `showHeading` | `boolean` | Whether to display the heading |
-| `instructions` | `string` (optional) | Instructional text shown below the heading |
-| `collapsible` | `boolean` | Whether the group can be collapsed |
-| `type` | `string` | Group type (used for layout context) |
+| Prop           | Type                | Description                                       |
+| -------------- | ------------------- | ------------------------------------------------- |
+| `children`     | `ReactElement[]`    | Child field components to render inside the group |
+| `heading`      | `string`            | The group heading/title                           |
+| `showHeading`  | `boolean`           | Whether to display the heading                    |
+| `instructions` | `string` (optional) | Instructional text shown below the heading        |
+| `collapsible`  | `boolean`           | Whether the group can be collapsed                |
+| `type`         | `string`            | Group type (used for layout context)              |
 
 `displayMode` is also consumed from `PConnFieldProps`.
 
+## Component Skeleton
+
+```typescript
+import { type ReactElement, useMemo } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface GroupProps extends PConnFieldProps {
+  children: ReactElement[];
+  heading: string;
+  showHeading: boolean;
+  instructions?: string;
+  collapsible: boolean;
+  type: string;
+}
+
+export default function Group(props: GroupProps) {
+  // 1. Registry lookup
+  const FieldGroup = getComponentFromRegistry('FieldGroup');
+
+  // 2. Destructure props
+  const { children, heading, showHeading, instructions, collapsible, displayMode, type } = props;
+
+  // 3. Derived flag
+  const isReadOnly = displayMode === 'DISPLAY_ONLY';
+
+  // 4. Memoized content grid — deps: [children, type, isReadOnly]
+  const content = useMemo(() => (
+    <GridContainer spacing={2}>
+      {children?.map(child => (
+        <GridItem fullWidth key={child.key}>{child}</GridItem>
+      ))}
+    </GridContainer>
+  ), [children, type, isReadOnly]);
+
+  // 5. Null guard
+  if (!children) return null;
+
+  // 6. Return FieldGroup wrapper
+  return (
+    <FieldGroup
+      name={showHeading ? heading : undefined}
+      collapsible={collapsible}
+      instructions={instructions}
+    >
+      {content}
+    </FieldGroup>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. **No state, no event handling** — purely structural/layout.
@@ -59,11 +105,17 @@ Grid container (spacing=2):
 ```
 
 **CSS-only grid layout:**
+
 ```css
-.field-group-children { display: grid; grid-template-columns: 1fr; gap: 16px; }
+.field-group-children {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 16px;
+}
 ```
 
 The `FieldGroup` component itself provides:
+
 - Optional heading/title above the children
 - Optional collapse/expand control
 - Optional instructions text
@@ -87,9 +139,9 @@ The `FieldGroup` component itself provides:
 
 Listed design systems are examples only.
 
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | `<fieldset>` or `<details>/<summary>` for collapsible |
-| MUI | `<Grid container spacing={2}>` with `<Grid size={{ xs: 12 }}>` per child |
-| Ant Design | `<Collapse>` panel or `<Card>` |
-| Chakra UI | `<Box>` or `<Accordion>` |
+| Design System      | Recommended Component                                                    |
+| ------------------ | ------------------------------------------------------------------------ |
+| Default (CSS only) | `<fieldset>` or `<details>/<summary>` for collapsible                    |
+| MUI                | `<Grid container spacing={2}>` with `<Grid size={{ xs: 12 }}>` per child |
+| Ant Design         | `<Collapse>` panel or `<Card>`                                           |
+| Chakra UI          | `<Box>` or `<Accordion>`                                                 |

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

@@ -0,0 +1,169 @@
+# Skill: Integer
+
+Integer-only text input that filters out decimal separators, 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 restricted to integer values. Actively filters out decimal (`.`) and thousands separator (`,`) characters as the user types, mimicking Pega's native integer field behavior. Delegates read-only rendering to `TextInput`.
+
+## Pega Metadata
+
+- **Pega Name:** `Integer`
+- **Type / Subtype:** `Field` / `Integer`
+- **Registration key:** `Integer` (in `component-map.ts`)
+
+## Props (component-specific)
+
+No props beyond `PConnFieldProps`. Import type as:
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Component Skeleton
+
+Follow this exact structure. The key differentiator from TextInput is the character filtering in `onChange`.
+
+```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 IntegerProps extends PConnFieldProps {}
+
+export default function Integer(props: IntegerProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 4. State
+  const [inputValue, setInputValue] = useState('');
+
+  // 5. useEffect: sync from store — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 6. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 7. Read-only return
+  if (readOnly) {
+    return <TextInput {...props} />;
+  }
+
+  // 8. Test ID
+  const testProps: any = { 'data-test-id': testId };
+
+  // 9. onChange with character filtering
+  function intOnChange(event) {
+    const disallowedChars = ['.', ','];
+    const theAttemptedValue = event.target.value;
+    const lastChar = theAttemptedValue.slice(-1);
+    if (disallowedChars.includes(lastChar)) {
+      event.target.value = theAttemptedValue.slice(0, -1);
+    }
+    setInputValue(event.target.value);
+  }
+
+  // 10. onBlur — commit to store
+  function handleBlur() {
+    handleEvent(actions, 'changeNblur', propName, inputValue);
+  }
+
+  // 11. Main render — text input (type='text', NOT 'number')
+  //     Key props:
+  //     - fullWidth, variant: 'outlined', size: 'small'
+  //     - type: 'text' (NOT 'number')
+  //     - value: inputValue, onChange: intOnChange
+  //     - onBlur: !readOnly ? handleBlur : undefined
+  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //     - required, disabled, error: status === 'error'
+  //     - htmlInput: { inputMode: 'numeric', pattern: '[0-9]*', ...testProps }
+  return <TextFieldWidget ... />;
+}
+```
+
+## 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 (character filtering):** Before updating local state, inspect the last character typed:
+   - If the last character is `.` or `,`, strip it from the value: `event.target.value = theAttemptedValue.slice(0, -1)`.
+   - Then update local state with the sanitized value.
+   - This "eating" of separator characters replicates Pega's native integer field behavior.
+4. **Input mode:** Set `inputMode='numeric'` and `pattern='[0-9]*'` on the input element for mobile keyboards.
+5. **Input type:** Use `type='text'` (NOT `type='number'`) — this avoids browser-specific number input quirks.
+6. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, inputValue)`.
+7. **Read-only:** Delegate to `TextInput`: `return <TextInput {...props} />`.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />`.
+- **`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:
+
+| Property      | Value                                        |
+| ------------- | -------------------------------------------- |
+| Width         | 100%                                         |
+| Size          | Small (~40px height)                         |
+| Variant       | Outlined                                     |
+| Border        | 1px solid                                    |
+| Border radius | 4px                                          |
+| Error state   | Red border + red helper text                 |
+| Input mode    | `numeric` (shows numeric keyboard on mobile) |
+| Pattern       | `[0-9]*`                                     |
+
+## Edge Cases & Special Logic
+
+- **Character filtering is inline** — do NOT use `type='number'` as it introduces inconsistent behavior across browsers (e.g., accepts `e`, `+`, `-` by default).
+- The disallowed characters array is `['.', ',']` — both decimal point and thousands separator are rejected.
+- Strip only the LAST character if it is disallowed — do not strip from anywhere else in the string (user may paste a valid integer that is then validated by blur).
+- `onBlur` is omitted 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:** Numeric text input (integer-only) — use `<input type="text" inputmode="numeric" pattern="[0-9]*">`.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------- |
+| Default (CSS only) | `<input type="text" inputMode="numeric" pattern="[0-9]*">`                                         |
+| MUI                | `<TextField type='text' slotProps={{ htmlInput: { inputMode: 'numeric', pattern: '[0-9]*' } }} />` |
+| Ant Design         | `<InputNumber precision={0} />` or `<Input />` with custom `onChange` filter                       |
+| Chakra UI          | `<NumberInput allowMouseWheel={false} />` or plain `<Input>` with filter                           |

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

@@ -0,0 +1,250 @@
+# Skill: Location
+
+Location input with Google Maps Places autocomplete, interactive map display, and optional geolocation (current location).
+
+> **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 text input that integrates with Google Maps Places API for address/location autocomplete. Optionally shows an interactive map with a marker. Supports an `onlyCoordinates` mode that stores `"lat, lng"` instead of address text. Includes a "get current location" button using the browser geolocation API.
+
+## Pega Metadata
+
+- **Pega Name:** `Location`
+- **Type / Subtype:** `Field` / `Text-Location`
+- **Registration key:** `Location` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop              | Type                 | Default | Description                                                              |
+| ----------------- | -------------------- | ------- | ------------------------------------------------------------------------ |
+| `coordinates`     | `string` (optional)  | `''`    | Comma-separated lat/lng string (e.g., `'18.5204, 73.8567'`)              |
+| `onlyCoordinates` | `boolean` (optional) | `false` | If `true`, store and display lat/lng coordinates instead of address text |
+| `showMap`         | `boolean` (optional) | —       | Show the interactive map in editable mode                                |
+| `showMapReadOnly` | `boolean` (optional) | —       | Show the map in read-only mode                                           |
+
+## Component Skeleton
+
+Follow this exact structure. This component is complex — integrates Google Maps API for places autocomplete, geolocation, and optional map display.
+
+```typescript
+import { useEffect, useState, useCallback, useRef } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import handleEvent from '../../helpers/event-utils';
+import './Location.css';
+
+interface LocationProps extends PConnFieldProps {
+  coordinates?: string;
+  onlyCoordinates?: boolean;
+  showMap?: boolean;
+  showMapReadOnly?: boolean;
+}
+
+const mapContainerStyle = { width: '100%', height: '300px', marginTop: '0px' };
+const defaultCenter = { lat: 18.5204, lng: 73.8567 };
+const disabledMapOptions = {
+  gestureHandling: 'none', keyboardShortcuts: false,
+  disableDefaultUI: true, clickableIcons: false,
+};
+
+export default function Location(props: LocationProps) {
+  // 1. Registry lookups
+  const TextInput = getComponentFromRegistry('TextInput');
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required = false, disabled = false, value = '',
+    validatemessage, status, readOnly = false, testId, displayMode,
+    hideLabel = false, placeholder, helperText,
+    coordinates = '', onlyCoordinates = false, showMap, showMapReadOnly,
+  } = props;
+
+  // 3. PConnect setup — note TWO property names
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const coordPropName = (pConn.getStateProps() as any).coordinates;
+
+  // 4. State
+  const [inputValue, setInputValue] = useState<string>(value ?? '');
+  const [mapCenter, setMapCenter] = useState(defaultCenter);
+  const [markerPosition, setMarkerPosition] = useState<{lat:number,lng:number} | null>(null);
+
+  // 5. Refs
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const autocompleteRef = useRef<google.maps.places.Autocomplete | null>(null);
+
+  // 6. Load Google Maps API
+  const { isLoaded } = useLoadScript({
+    googleMapsApiKey: pConn.getGoogleMapsAPIKey?.() || '',
+    libraries: ['places', 'geocoding'],
+  });
+
+  // 7. Error flag
+  const hasError = status === 'error' && !!validatemessage && !disabled;
+
+  // 8. useEffect: sync value + coordinates — deps: [value, coordinates, onlyCoordinates]
+  //    → see Behavioral Contract #3
+
+  // 9. handleChange (manual text input) — useCallback
+  //    Commits immediately, clears coordinates if input emptied
+
+  // 10. handlePlaceChanged — useCallback
+  //     Reads place from autocompleteRef, extracts lat/lng,
+  //     stores address or coordinates based on onlyCoordinates flag
+
+  // 11. useEffect: init Places Autocomplete — deps: [isLoaded, handlePlaceChanged]
+  //     Guard: isLoaded && inputRef.current && !autocompleteRef.current
+
+  // 12. handleGetCurrentLocation — useCallback
+  //     Uses navigator.geolocation.getCurrentPosition
+  //     If onlyCoordinates: store coords directly
+  //     Else: reverse geocode via google.maps.Geocoder
+
+  // 13. 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" />;
+  }
+
+  // 14. Map element (shared between readOnly and editable)
+  //     opacity: disabled ? 0.7 : 1, options: disabled ? disabledMapOptions : undefined
+
+  // 15. Read-only return
+  if (readOnly) {
+    return <div><TextInput {...props} />{isLoaded && showMapReadOnly && map}</div>;
+  }
+
+  // 16. Main render
+  //     - Error alert ABOVE input if hasError
+  //     - Guard: only render TextField when isLoaded
+  //     - TextField with inputRef, endAdornment location icon button
+  //     - Map below if isLoaded && showMap
+  return <div>...</div>;
+}
+```
+
+## Behavioral Contract
+
+1. **APIs required:**
+   - Google Maps JavaScript API with `places` and `geocoding` libraries
+   - API key obtained from `pConn.getGoogleMapsAPIKey?.() || ''`
+2. **Local state:**
+   - `inputValue` (string): shown in the text input
+   - `mapCenter` (`{lat, lng}`): default `{ lat: 18.5204, lng: 73.8567 }` (Pune, India)
+   - `markerPosition` (`{lat, lng} | null`)
+3. **Value sync:** `useEffect` watching `value`, `coordinates`, `onlyCoordinates`:
+   - If `onlyCoordinates && coordinates`: `setInputValue(coordinates)`
+   - Else: `setInputValue(value ?? '')`
+   - If `coordinates` exists: parse `lat, lng`, update `mapCenter` and `markerPosition`
+4. **Places Autocomplete (init):** `useEffect` watching `isLoaded` — once Maps API loads and `inputRef.current` is set, attach `new google.maps.places.Autocomplete(inputRef.current)` and add `place_changed` listener.
+5. **On place changed:**
+   - Get `place.geometry.location` → extract `lat`, `lng`
+   - If `onlyCoordinates`: `inputValue = "${lat}, ${lng}"`, commit this as the value AND update `coordinates` property
+   - Else: `inputValue = place.formatted_address`, commit address as value, update `coordinates` property separately: `actions.updateFieldValue(coordPropName, coordinateString)`
+   - Update `mapCenter` and `markerPosition`
+6. **On text change (manual):**
+   - Update `inputValue` and commit immediately via `handleEvent(actions, 'changeNblur', propName, newValue)`
+   - If input cleared and `coordPropName` exists: `actions.updateFieldValue(coordPropName, '')`; `setMarkerPosition(null)`
+7. **Get current location button:**
+   - Use `navigator.geolocation.getCurrentPosition()`
+   - If `onlyCoordinates`: store `"lat, lng"` as value and coordinates
+   - Else: reverse-geocode using `google.maps.Geocoder`, store address as value, `"lat, lng"` as coordinates
+8. **Coordinate property name:** `coordPropName = (pConn.getStateProps() as any).coordinates` — separate from the main `propName`
+9. **Error display:** If `status === 'error' && !!validatemessage && !disabled`, show an error alert ABOVE the input.
+10. **Read-only:** Delegate text to `TextInput`, optionally show map if `showMapReadOnly`.
+
+### Map configuration (disabled state)
+
+When `disabled`, map options disable all interactions:
+
+- `gestureHandling: 'none'`, `keyboardShortcuts: false`, `disableDefaultUI: true`, `clickableIcons: false`
+- Map opacity: `0.7` when disabled
+
+### CSS for Google Maps autocomplete dropdown z-index:
+
+```css
+/* Location.css */
+.pac-container {
+  z-index: 2147483647;
+}
+```
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />` — raw address/coordinates string.
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+
+## Read-Only Rendering
+
+```
+<div>
+  <TextInput {...props} />
+  {isLoaded && showMapReadOnly && <GoogleMap ... />}
+</div>
+```
+
+## Visual Specifications
+
+| Property             | Value                                              |
+| -------------------- | -------------------------------------------------- |
+| Width                | 100%                                               |
+| Input variant        | Default (outlined, from `TextField`)               |
+| Trailing icon        | Location pin icon button (for current location)    |
+| Error alert          | Alert banner ABOVE the input field when `hasError` |
+| Map container        | `width: 100%`, `height: 300px`, `marginTop: 0px`   |
+| Map render           | Only shown when `isLoaded && (showMap              |     | showMapReadOnly)` |
+| Disabled map opacity | `0.7`                                              |
+
+**CSS companion file required:** `Location.css` with:
+
+```css
+.pac-container {
+  z-index: 2147483647;
+}
+```
+
+This ensures the Google Maps autocomplete dropdown appears above modal/dialog overlays.
+
+**CSS-only implementation notes:**
+
+- Location pin button: `<button>` with `position: absolute; right: 8px; top: 50%; transform: translateY(-50%);`
+
+## Edge Cases & Special Logic
+
+- **`isLoaded` guard:** Only render the `TextField` and map after Google Maps API is fully loaded.
+- **`onlyCoordinates` mode:** The stored `value` is `"lat, lng"` format; coordinates and address are the same.
+- **Dual property:** The component writes to TWO properties — `propName` (address or coordinates) and `coordPropName` (coordinates). `coordPropName` may be undefined if the Pega config doesn't include a coordinates property.
+- **Autocomplete ref lifecycle:** `autocompleteRef` is only initialized once (when `!autocompleteRef.current`). The `handlePlaceChanged` callback must be stable (`useCallback` with deps).
+- **Map default center:** Pune, India — `{ lat: 18.5204, lng: 73.8567 }`.
+- Google Maps Geocoder is only called in non-`onlyCoordinates` geolocation mode for reverse geocoding.
+
+## Dependencies
+
+- Google Maps JavaScript API (loaded dynamically via `@react-google-maps/api` or equivalent loader).
+- `@react-google-maps/api` — `GoogleMap`, `Marker`, `useLoadScript`.
+- `handleEvent` from `../../helpers/event-utils`.
+- `getComponentFromRegistry('TextInput')` for read-only.
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- A location pin icon.
+
+**CSS companion:** `Location.css` — must be imported to fix autocomplete z-index.
+
+## Design System Mapping
+
+**UI control type:** Text input with location autocomplete dropdown + optional map.
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                   |
+| ------------------ | ----------------------------------------------------------------------- |
+| Default (CSS only) | `<input type="text">` + Google Maps Autocomplete API + Google Map embed |
+| MUI                | `<TextField>` + `InputAdornment` for icon + `@react-google-maps/api`    |
+| Ant Design         | `<Input suffix={<LocationIcon />}>` + Google Maps                       |
+| Chakra UI          | `<InputGroup>` + `<InputRightElement>` + Google Maps                    |