@pega/sdk 0.0.4 → 0.0.6

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

@@ -1,203 +0,0 @@
-# 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)                         |
-
-## 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/.github/skills/run-and-verify.md

@@ -1,70 +0,0 @@
-# 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
-```

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

@@ -1,321 +0,0 @@
-# Skill: Template Components
-
-Create or replace template components (layouts and page structures) in the react-sdk-reference application. Template components arrange child components into visual layouts (columns, tabs, forms, pages).
-
----
-
-## Architecture Overview
-
-```
-src/components/template/<ComponentName>/
-├── <ComponentName>.tsx      # Component implementation
-├── index.tsx                # Re-export (if present)
-├── <ComponentName>.css      # Styles (CSS file, optional)
-├── utils.ts                 # Template-specific utilities (optional)
-└── config-ext.json          # Metadata (optional)
-```
-
-Some templates have nested sub-templates:
-
-```
-src/components/template/TwoColumn/
-├── TwoColumn/TwoColumn.tsx
-├── TwoColumnPage/TwoColumnPage.tsx
-└── TwoColumnTab/TwoColumnTab.tsx
-```
-
----
-
-## Props Interface
-
-Template components extend `PConnProps`:
-
-```typescript
-import type { PConnProps } from '../../../types/PConnProps';
-
-interface PConnProps {
-  getPConnect: () => typeof PConnect;
-}
-```
-
-Templates typically receive children through `getPConnect().getChildren()` rather than React `children` prop, though layout templates (TwoColumn, OneColumn) receive React children directly.
-
----
-
-## Implementation Patterns
-
-### Layout Template (renders React children in grid)
-
-Used for: TwoColumn, OneColumn, NarrowWide, WideNarrow
-
-This pattern is design-system agnostic. The `// [DS GRID]` section must be replaced with your design system's grid or flex layout primitive — see the "Design System Adaptation" section below.
-
-```typescript
-import type { PropsWithChildren, ReactElement } from 'react';
-// Import your design system layout primitive here:
-// e.g. import { Grid } from 'antd';
-// e.g. import { SimpleGrid } from '@chakra-ui/react';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface TwoColumnProps extends PConnProps {
-  templateCol?: string; // e.g. '1fr 1fr', '2fr 1fr'
-}
-
-export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
-  const { children, templateCol = '1fr 1fr' } = props;
-  const childrenToRender = children as ReactElement[];
-
-  // Parse templateCol into column width ratios
-  // Strip unit suffixes, split on whitespace, convert to numbers
-  const colArray = templateCol.replaceAll(/[a-z]+/g, '').split(/\s/).map(Number);
-  const totalCols = colArray.reduce((v, itm) => itm + v, 0);
-  // colArray[0] / totalCols = left column fraction
-  // colArray[1] / totalCols = right column fraction
-
-  // [DS GRID] — render two children in a responsive grid using the computed ratios
-  // On mobile (narrow viewport): both columns should stack to full width
-  // On desktop: apply the computed left/right ratio
-  return (
-    <YourDesignSystemGrid>
-      <YourDesignSystemColumn ratio={colArray[0] / totalCols}>
-        {childrenToRender[0]}
-      </YourDesignSystemColumn>
-      <YourDesignSystemColumn ratio={colArray[1] / totalCols}>
-        {childrenToRender[1]}
-      </YourDesignSystemColumn>
-    </YourDesignSystemGrid>
-  );
-}
-```
-
----
-
-## Design System Adaptation (Layout Templates Only)
-
-> Form templates and page templates use the PConnect bridge pattern and do **not** use any design system primitives. This section applies only to layout templates: TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants.
-
-**1. Check the component-specific skill file** — `.github/skills/template-skills/<ComponentName>.md` contains a **Design System Mapping** table where available. Use it as a starting point.
-
-**2. If the chosen design system is not listed** — use the **component purpose** description to identify the appropriate DS layout primitive (grid, flex, columns).
-
-**3. Discover the API from installed packages** — confirm layout component names and props from `.d.ts` before writing JSX:
-
-```bash
-find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Grid\|Columns\|Flex" | head -5
-grep -A 30 "interface.*Props" <path-to-file>
-```
-
-**4. Column ratio mapping** — the `templateCol` prop (e.g., `'2fr 1fr'`) gives you fractional widths. Map to your DS's column system:
-
-| `templateCol` | Fraction  | MUI 12-col | CSS `grid-template-columns` |
-| ------------- | --------- | ---------- | --------------------------- |
-| `'1fr 1fr'`   | 50% / 50% | 6 / 6      | `1fr 1fr`                   |
-| `'2fr 1fr'`   | 67% / 33% | 8 / 4      | `2fr 1fr`                   |
-| `'1fr 2fr'`   | 33% / 67% | 4 / 8      | `1fr 2fr`                   |
-
-**5. Responsive behavior** — on mobile, both columns must stack to full width. Use your DS's responsive breakpoint props or a CSS media query.
-
-### Form Template (renders children via PConnect bridge)
-
-Used for: DefaultForm, HierarchicalForm
-
-```typescript
-import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
-import connectToState from '../../helpers/state-utils';
-import type { PConnProps } from '../../../types/PConnProps';
-
-interface DefaultFormProps extends PConnProps {
-  NumCols: string;
-  instructions: string;
-}
-
-export default function DefaultForm(props: DefaultFormProps) {
-  const { getPConnect, NumCols = '1' } = props;
-
-  // Get children from the first region
-  const arChildren = getPConnect().getChildren()[0].getPConnect().getChildren();
-
-  // Wrap each child in a PConnect component
-  const dfChildren = arChildren?.map((kid, i) => (
-    createElement(createPConnectComponent(), { ...kid, key: `child-${i}` })
-  ));
-
-  return <div className={`form-${NumCols}-col`}>{dfChildren}</div>;
-}
-```
-
-### Page Template (renders regions from PConnect children)
-
-Used for: CaseView, DefaultPage, ObjectPage
-
-```typescript
-import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
-import type { PConnProps } from '../../../types/PConnProps';
-
-interface CaseViewProps extends PConnProps {
-  header?: string;
-  subheader?: string;
-}
-
-export default function CaseView(props: CaseViewProps) {
-  const { getPConnect, header } = props;
-  const pConn = getPConnect();
-  const children = pConn.getChildren();
-
-  return (
-    <div>
-      <h2>{header}</h2>
-      {children.map((child, index) => (
-        createElement(createPConnectComponent(), { ...child, key: `region-${index}` })
-      ))}
-    </div>
-  );
-}
-```
-
----
-
-## Rendering Children
-
-Templates use two patterns to render child components:
-
-### 1. React children (layout templates)
-
-```typescript
-// TwoColumn, OneColumn, etc. receive children as React props
-const { children } = props;
-const childrenToRender = children as ReactElement[];
-```
-
-### 2. PConnect children (form/page templates)
-
-```typescript
-import { createElement } from 'react';
-import createPConnectComponent from '../../helpers/react_pconnect';
-
-// Get child PConnect objects
-const children = getPConnect().getChildren();
-
-// Render each child through the PConnect bridge
-children.map((child, i) => createElement(createPConnectComponent(), { ...child, key: `child-${i}` }));
-```
-
-### 3. State-connected children (DefaultForm pattern)
-
-```typescript
-import connectToState from '../../helpers/state-utils';
-import createPConnectComponent from '../../helpers/react_pconnect';
-
-// connectToState HOC subscribes to Redux store for visibility/props
-const Child = connectToState(mapStateToProps)((props) => {
-  const { key, visibility, ...rest } = props;
-  return createElement(createPConnectComponent(), { ...rest, key, visibility });
-});
-```
-
----
-
-## Helper Utilities
-
-### `createPConnectComponent` (from `../../helpers/react_pconnect`)
-
-Factory that returns the PConnect bridge component. Used to render child PConnect objects:
-
-```typescript
-import createPConnectComponent from '../../helpers/react_pconnect';
-createElement(createPConnectComponent(), childPConnectProps);
-```
-
-### `connectToState` (from `../../helpers/state-utils`)
-
-HOC that connects a component to the Redux store for visibility and dynamic props:
-
-```typescript
-import connectToState from '../../helpers/state-utils';
-const ConnectedChild = connectToState(mapStateToProps)(ChildComponent);
-```
-
-### `getInstructions` (from `../../helpers/template-utils`)
-
-Extracts instruction text for forms:
-
-```typescript
-import { getInstructions } from '../../helpers/template-utils';
-const instructions = getInstructions(getPConnect(), props.instructions);
-```
-
----
-
-## Registration
-
-Register templates in `src/components/component-map.ts`:
-
-```typescript
-import MyTemplate from './template/MyTemplate';
-
-// In getSampleComponentMap():
-{
-  ...sdkComponents,
-  MyTemplate,  // Key must match Pega component name
-}
-```
-
-For nested templates (e.g., TwoColumn/TwoColumnPage/TwoColumnTab), register each separately:
-
-```typescript
-import TwoColumn from './template/TwoColumn/TwoColumn/TwoColumn';
-import TwoColumnPage from './template/TwoColumn/TwoColumnPage';
-import TwoColumnTab from './template/TwoColumn/TwoColumnTab';
-
-{
-  TwoColumn,
-  TwoColumnPage,
-  TwoColumnTab,
-}
-```
-
----
-
-## Existing Template Components
-
-| Component                                       | Type       | Description                          |
-| ----------------------------------------------- | ---------- | ------------------------------------ |
-| AdvancedSearch                                  | Page       | Advanced search with filters         |
-| AppShell                                        | Page       | Top-level app layout with nav        |
-| BannerPage                                      | Page       | Page with banner section             |
-| CaseSummary                                     | Page       | Case summary header                  |
-| CaseView                                        | Page       | Main case view with regions          |
-| CaseViewActionsMenu                             | Widget     | Case action dropdown menu            |
-| Confirmation                                    | Page       | Case completion confirmation         |
-| DataReference                                   | Form       | Embedded data reference lookup       |
-| DefaultForm                                     | Form       | Standard form layout (1/2/3 columns) |
-| DefaultPage                                     | Page       | Default page structure               |
-| Details / DetailsTwoColumn / DetailsThreeColumn | Layout     | Details region layouts               |
-| FieldGroupTemplate                              | Form       | Repeating field group                |
-| HierarchicalForm                                | Form       | Multi-step hierarchical form         |
-| InlineDashboard                                 | Page       | Inline dashboard container           |
-| ListPage                                        | Page       | List/table page                      |
-| ListView                                        | Page       | Data table with filtering/sorting    |
-| MultiReferenceReadOnly                          | Display    | Read-only multi-reference display    |
-| NarrowWide / WideNarrow                         | Layout     | Asymmetric two-column layouts        |
-| ObjectPage                                      | Page       | Object detail page                   |
-| OneColumn                                       | Layout     | Single-column layout                 |
-| PromotedFilters                                 | Widget     | Filter bar for lists                 |
-| SimpleTable                                     | Table      | Editable/read-only data tables       |
-| SingleReferenceReadOnly                         | Display    | Read-only single reference           |
-| SubTabs                                         | Navigation | Tab container                        |
-| TwoColumn                                       | Layout     | Two-column layout                    |
-| WssNavBar                                       | Navigation | WSS navigation bar                   |
-
----
-
-## Key Conventions
-
-1. **Default export** — `export default function TemplateName`.
-2. **Children from PConnect** — Use `getPConnect().getChildren()` to access child regions.
-3. **createElement pattern** — Use `createElement(createPConnectComponent(), childProps)` to render PConnect children.
-4. **CSS files** — Template-specific styles go in `<TemplateName>.css` alongside the component.
-5. **Responsive** — Use MUI Grid with `xs: 12` for mobile and `md: <size>` for desktop breakpoints.
-6. **templateCol** — Layout templates often receive a `templateCol` prop (e.g., `"1fr 1fr"`, `"2fr 1fr"`) to control column ratios.