@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 Field group container that wraps child fields in a collapsible section with an optional heading and instructions.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,105 +14,54 @@ A layout/structural component (not a form input). Wraps a set of child field com
 
 - **Pega Name:** `Group`
 - **Type / Subtype:** `Field` / `Group`
-- **Registration key:** `Group` (in `component-map.ts`)
-
-## 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)              |
-
-`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>
-  );
-}
-```
+- **Registration key:** `Group` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Input          | Type                    | Description                                       |
+| -------------- | ----------------------- | ------------------------------------------------- |
+| `children`     | array of child elements | 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 the project's field input contract.
+
+## Implementation Structure
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldGroup`). Define the input contract as the project's field input contract extended with `children` (array of child elements), `heading: string`, `showHeading: boolean`, `instructions?: string`, `collapsible: boolean`, and `type: string`.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldGroup` via the project's component registry.
+2. **Receive inputs** — `children`, `heading`, `showHeading`, `instructions`, `collapsible`, `displayMode`, `type`.
+3. **Derived flag** — `isReadOnly = displayMode === 'DISPLAY_ONLY'`.
+4. **Memoized content grid** (dependencies: `children`, `type`, `isReadOnly`) — build a grid container (spacing 2) where each child is wrapped in a full-width grid item, preserving each child's key.
+5. **Null guard** — if `!children`, return `null`.
+6. **Return `FieldGroup` wrapper** — pass `name` as `heading` only when `showHeading` is true (otherwise `undefined`), plus `collapsible` and `instructions`, wrapping the memoized content grid.
 
 ## Behavioral Contract
 
 1. **No state, no event handling** — purely structural/layout.
 2. **`isReadOnly` flag:** `isReadOnly = displayMode === 'DISPLAY_ONLY'` — passed through to grid for layout context.
-3. **Content grid:** Build a responsive grid of children using `useMemo` (memoized based on `children`, `type`, `isReadOnly`):
-   - Each child gets a full-width grid item (`xs: 12` in a 12-column grid, or equivalent `100%` column).
-   - Children are mapped with their `key` prop preserved.
+3. **Content grid:** Build a responsive grid of children using a memoized computation (dependencies: `children`, `type`, `isReadOnly`):
+   - Each child gets a full-width grid item (100% column width in a 12-column grid system or equivalent).
+   - Children are mapped with their unique key preserved.
 4. **Null guard:** If `!children`, return `null`.
 5. **Heading:** Pass `showHeading ? heading : undefined` to `FieldGroup` — if `showHeading` is false, heading is `undefined` (not shown).
-6. **FieldGroup:** Resolved via `getComponentFromRegistry('FieldGroup')`. Receives `name`, `collapsible`, and `instructions` props.
+6. **FieldGroup:** Resolved via the project's component registry with key `'FieldGroup'`. Receives `name`, `collapsible`, and `instructions` inputs.
 
 ## Display Mode Rendering
 
-`displayMode` is not explicitly handled — it's passed through as a prop for context. `FieldGroup` and children handle their own display mode behavior.
+`displayMode` is not explicitly handled — it's passed through as an input for context. `FieldGroup` and children handle their own display mode behavior.
 
 ## Visual Specifications
 
-The visual appearance is determined by the `FieldGroup` design system extension component. `Group` itself only applies grid layout to children:
-
-```
-Grid container (spacing=2):
-  per child → Grid item (xs: 12, full width)
-```
+The visual appearance is determined by the `FieldGroup` design system extension component. `Group` itself only applies grid layout to children: a grid container with spacing 2, where each child occupies a full-width grid item.
 
-**CSS-only grid layout:**
-
-```css
-.field-group-children {
-  display: grid;
-  grid-template-columns: 1fr;
-  gap: 16px;
-}
-```
+**Visual-only styling notes:** The children grid uses a single-column layout with a consistent gap between items.
 
 The `FieldGroup` component itself provides:
 
@@ -123,25 +72,17 @@ The `FieldGroup` component itself provides:
 
 ## Edge Cases & Special Logic
 
-- **`useMemo` dependencies:** `[children, type, isReadOnly]` — the grid re-renders only when these change, not on every parent render.
-- Children must have stable `key` props for React reconciliation.
+- **Memoized computation dependencies:** `children`, `type`, `isReadOnly` — the grid re-renders only when these change, not on every parent render.
+- Children must have stable keys for reconciliation.
 - `instructions` may be undefined — `FieldGroup` should handle this gracefully.
 
 ## Dependencies
 
-- `getComponentFromRegistry('FieldGroup')` — design system extension providing the collapsible container.
-- `useMemo` from React.
-- Grid layout component (e.g., MUI `Grid`).
+- The project's component registry to resolve `FieldGroup` — the design system extension providing the collapsible container.
+- A grid layout mechanism for arranging children in a single-column layout with consistent spacing.
 
 ## Design System Mapping
 
 **UI control type:** Collapsible field group container with heading.
 
-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>`                                                 |
+When implementing in a specific design system, map the following: a grid container component with consistent spacing (gap of 2 units) where each child occupies a full-width row, and a collapsible section/panel component for the outer `FieldGroup` wrapper. The collapsible panel should support an optional title, collapse/expand toggle, and an instructions area. Native HTML equivalents include `<fieldset>` or `<details>/<summary>` for collapsibility.

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

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,118 +14,53 @@ Renders a single-line text input restricted to integer values. Actively filters
 
 - **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 ... />;
-}
-```
+- **Registration key:** `Integer` (in the project's component map)
+
+## Inputs (component-specific)
+
+No inputs beyond the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Follow this exact structure. The key differentiator from TextInput is the character filtering in the change handler.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `TextInput` and `FieldValueList`) and the project's event-commit utility (for committing value changes to the store). Define the input contract as the project's field input contract with no additional fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookups** — resolve `TextInput` and `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`.
+3. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`.
+4. **Local state** — `inputValue` initialized to `''`.
+5. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever it changes.
+6. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+7. **Read-only return** — when `readOnly` is true, render the `TextInput` component with all inputs passed through directly (full delegation).
+8. **Test ID** — build a test-id attribute from `testId`.
+9. **Change handler with character filtering** — read the attempted value from the change event, check whether its last character is a disallowed character (`.` or `,`), and if so strip that last character before updating the DOM value; then update local `inputValue` with the (possibly trimmed) value. This mimics Pega's native integer field behavior of blocking decimal/thousands separators as the user types.
+10. **Blur handler** — commit to store via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+11. **Render** — a text input configured with: input type `text` (explicitly NOT `number`, to retain full control over character filtering), full width, outlined style, small size, current `inputValue`, the change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and HTML input attributes `inputMode: 'numeric'` and `pattern: '[0-9]*'` merged with the test-id attribute to hint numeric keyboards on mobile while still filtering as plain text.
 
 ## Behavioral Contract
 
-1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop (`''` default).
-2. **Sync from store:** `useEffect` watching `value` → `setInputValue(value)`.
+1. **Local state:** Maintain `inputValue` (string). Initialize from `value` input (`''` default).
+2. **Sync from store:** A lifecycle effect watching `value` updates `inputValue`.
 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)`.
+   - If the last character is `.` or `,`, strip it from the value (slice off the last character).
    - 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} />`.
+6. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+7. **Read-only:** Delegate to `TextInput`, passing all inputs through.
 
 ## Display Mode Rendering
 
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} />`.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value`.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Delegate to `TextInput`: `return <TextInput {...props} />`.
+Delegate to `TextInput`, passing all inputs through.
 
 ## Visual Specifications
 
@@ -147,23 +82,21 @@ Identical to `TextInput` visually:
 - **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`.
+- The blur handler is omitted when `readOnly`.
 
 ## Dependencies
 
-- `handleEvent` from `../../helpers/event-utils`
-- `getComponentFromRegistry('TextInput')` — for read-only delegation
-- `getComponentFromRegistry('FieldValueList')` — for display modes
+- The project's event-commit utility.
+- The project's component registry, resolving `TextInput` — for read-only delegation.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 ## Design System Mapping
 
-**UI control type:** Numeric text input (integer-only) — use `<input type="text" inputmode="numeric" pattern="[0-9]*">`.
+**UI control type:** Numeric text input (integer-only).
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                                                              |
-| ------------------ | -------------------------------------------------------------------------------------------------- |
-| Default (CSS only) | `<input type="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                           |
+- **Text input** → use the DS's text input with `type='text'`, `inputMode='numeric'`, `pattern='[0-9]*'`
+- **Character filtering** → implement in the change handler (strip `.` and `,` from the last character)
+- **Read-only mode** → delegate to the `TextInput` component
+- **Error state** → the DS's error/danger visual state