@pega/sdk 0.0.5 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/widget-components.md

@@ -1,49 +1,20 @@
 # Skill: Widget Components
 
-Create or replace widget components in the react-sdk-reference application. Widgets are self-contained UI blocks that fetch their own data from Pega APIs (data pages, case info) and render interactive features (ToDo lists, attachments, case history, etc.).
+Create or replace widget components in the project. Widgets are self-contained UI blocks that fetch their own data from Pega APIs (data pages, case info) and render interactive features (ToDo lists, attachments, case history, etc.).
 
 ---
 
 ## Architecture Overview
 
-```
-src/components/widget/<ComponentName>/
-├── <ComponentName>.tsx      # Component implementation
-├── index.tsx                # Re-export (if present)
-├── <ComponentName>.css      # Styles (optional)
-├── <ComponentName>Utils.ts  # Widget-specific utilities (optional)
-├── <ComponentName>.types.ts # Type definitions (optional)
-└── config-ext.json          # Metadata (optional)
-```
+Each widget lives in its own folder under the project's widget components directory, named after the component. The folder typically contains: the component implementation file; optionally a re-export module; optionally a companion stylesheet; optionally a widget-specific utilities module; optionally a types definition module; and optionally a metadata file.
 
 ---
 
-## Props Interface
+## Input Contract
 
-Widget components extend `PConnProps`:
+Widget components extend the project's **base component interface** (which provides `getPConnect`). A typical widget input contract adds widget-specific inputs provided by the platform, such as `datasource`, `headerText`, and `context`.
 
-```typescript
-import type { PConnProps } from '../../../types/PConnProps';
-
-interface MyWidgetProps extends PConnProps {
-  // Widget-specific props provided by the platform
-  datasource?: any;
-  headerText?: string;
-  context?: string;
-}
-```
-
-Some widgets extend `PConnFieldProps` when they behave like form fields (e.g., Attachment):
-
-```typescript
-import type { PConnFieldProps } from '../../../types/PConnProps';
-
-interface AttachmentProps extends Omit<PConnFieldProps, 'value'> {
-  value: any; // Attachment list (not a string)
-  allowMultiple: boolean;
-  extensions: string;
-}
-```
+Some widgets extend the project's **field input contract** when they behave like form fields (e.g., Attachment): the Attachment input contract overrides `value` to be `any` (an attachment list rather than a string), and adds `allowMultiple` and `extensions`.
 
 ---
 
@@ -51,114 +22,47 @@ interface AttachmentProps extends Omit<PConnFieldProps, 'value'> {
 
 ### Data-Fetching Widget
 
-Widgets typically fetch data from Pega data pages on mount. This pattern is design-system agnostic. The `// [DS RENDER]` section must be replaced with your design system's presentation primitives (card, list, table, etc.) — see "Design System Adaptation" below.
-
-```typescript
-import { useState, useEffect } from 'react';
-// Import your design system components here:
-// e.g. import { Card, List } from 'antd';
-// e.g. import { Card, UnorderedList } from '@chakra-ui/react';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface MyWidgetProps extends PConnProps {
-  datasource?: any;
-  headerText?: string;
-}
-
-export default function MyWidget(props: MyWidgetProps) {
-  const { getPConnect, datasource, headerText = 'My Widget' } = props;
-  const pConn = getPConnect();
-
-  const [data, setData] = useState<any[]>([]);
-  const [loading, setLoading] = useState(true);
-
-  // 1. Fetch data from a Pega data page on mount
-  // This block is always the same regardless of design system
-  useEffect(() => {
-    const context = pConn.getContextName();
-    PCore.getDataPageUtils()
-      .getDataAsync(
-        datasource?.source,  // Data page name (e.g., 'D_WorkList')
-        context,
-        {},                  // Parameters
-        { pageNumber: 1, pageSize: 10 },
-        { select: [{ field: 'pyID' }, { field: 'pyLabel' }] },
-        { invalidateCache: true }
-      )
-      .then(response => {
-        setData(Array.isArray(response?.data) ? response.data : []);
-        setLoading(false);
-      })
-      .catch(() => setLoading(false));
-  }, []);
-
-  // 2. Loading state — replace with your DS loading indicator if available
-  if (loading) return <div>Loading...</div>;
-
-  // 3. [DS RENDER] — replace with your design system's card/list/table primitives
-  // See "Design System Adaptation" section below for guidance
-  return (
-    <YourDesignSystemCard>
-      <YourDesignSystemCardHeader title={headerText} />
-      <YourDesignSystemCardContent>
-        <YourDesignSystemList>
-          {data.map((item, i) => (
-            <YourDesignSystemListItem key={i}>{item.pyLabel}</YourDesignSystemListItem>
-          ))}
-        </YourDesignSystemList>
-      </YourDesignSystemCardContent>
-    </YourDesignSystemCard>
-  );
-}
-```
+Widgets typically fetch data from Pega data pages on mount. This pattern is design-system agnostic. The design-system render section must be replaced with your design system's presentation primitives (card, list, table, etc.) — see "Design System Adaptation" below.
+
+**Module Setup:** The component depends on local state management and a lifecycle effect for data fetching, plus the design system's presentation components (card, list, etc.). Define the input contract as an extension of the project's base component interface with `datasource` and `headerText` fields.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `getPConnect`, `datasource`, and `headerText` (default `'My Widget'`) from inputs; call `getPConnect()` into `pConn`. Declare `data` local state (array, default empty) and `loading` local state (boolean, default `true`).
+2. **Fetch data from a Pega data page on mount** — this block is always the same regardless of design system. In a lifecycle effect that runs once on initialization: resolve `context` via `pConn.getContextName()`; call `PCore.getDataPageUtils().getDataAsync(datasource?.source, context, {}, { pageNumber: 1, pageSize: 10 }, { select: [{ field: 'pyID' }, { field: 'pyLabel' }] }, { invalidateCache: true })` — where `datasource?.source` is the data page name (e.g. `'D_WorkList'`); on success, set `data` to `response?.data` when it is an array (otherwise an empty array) and set `loading` to `false`; on failure, just set `loading` to `false`.
+3. **Loading state** — while `loading` is true, render a simple loading placeholder (replace with the design system's loading indicator if available).
+4. **Design-system render** — once loaded, render the design system's card/list primitives: a card with a header showing `headerText`, and inside the card content, a list where each `data` item (keyed by index) renders `item.pyLabel`. See "Design System Adaptation" below for guidance on choosing the actual DS components.
 
 ---
 
 ## Design System Adaptation
 
-The PCore data-fetching logic (all `PCore.*` calls) is always identical regardless of design system. Only the `// [DS RENDER]` section changes.
+The PCore data-fetching logic (all `PCore.*` calls) is always identical regardless of design system. Only the design-system render section changes.
 
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/widget-skills/<ComponentName>.md` contains a **Design System Mapping** table where available. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/widget-skills/<ComponentName>.md` contains a **Design System Mapping** section 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 primitives (card, list, table, button, badge, etc.).
+**2. If the chosen design system is not covered** — use the component purpose description to identify the appropriate DS primitives (card, list, table, button, badge, etc.).
 
-**3. Discover the API from installed packages** — confirm component names and props from `.d.ts` before writing JSX:
-
-```bash
-find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Card\|List\|Table" | head -5
-grep -A 30 "interface.*Props" <path-to-file>
-```
+**3. Discover the API from installed packages** — confirm component names and inputs from the design system's type declaration files before writing the render markup.
 
 **4. Common widget UI primitive mapping:**
 
 | Widget pattern       | Typical DS equivalent                           |
 | -------------------- | ----------------------------------------------- |
-| Container with title | `Card` + header/title prop, or `Panel`, `Box`   |
-| Item list            | `List`, `UnorderedList`, or `Table` rows        |
-| Loading indicator    | `Spinner`, `Skeleton`, `Loading`                |
-| Action button        | `Button` with `onClick`                         |
-| Status badge         | `Badge`, `Tag`, `Chip`                          |
-| Empty state          | DS empty/placeholder component or plain `<div>` |
+| Container with title | Card + header/title, or Panel, Box              |
+| Item list            | List, or Table rows                             |
+| Loading indicator    | Spinner, Skeleton, Loading                      |
+| Action button        | Button with click handler                       |
+| Status badge         | Badge, Tag, Chip                                |
+| Empty state          | DS empty/placeholder component or plain element |
 
-**5. Icons** — if the DS has a companion icon package, read its exports before using any icon name. Never guess icon names.
+**5. Icons** — if the DS has a companion icon package, check its exports before using any icon name. Never guess icon names.
 
 ---
 
 ### Action Widget (opens assignments/cases)
 
-```typescript
-function openAssignment(assignment) {
-  const { classname, ID } = assignment;
-  const context = getPConnect().getContextName();
-  const options = { containerName: 'primary', channelName: '' };
-
-  PCore.getMashupApi().openAssignment(ID, classname, options);
-}
-
-function createCase(caseType) {
-  PCore.getMashupApi().createCase(caseType, PCore.getConstants().APP.APP);
-}
-```
+Define `openAssignment(assignment)`: resolve `classname` and `ID` from `assignment`; resolve `context` via `getPConnect().getContextName()`; build `options = { containerName: 'primary', channelName: '' }`; then call `PCore.getMashupApi().openAssignment(ID, classname, options)`. Define `createCase(caseType)` to call `PCore.getMashupApi().createCase(caseType, PCore.getConstants().APP.APP)`.
 
 ---
 
@@ -166,69 +70,29 @@ function createCase(caseType) {
 
 ### Data Pages
 
-```typescript
-// Fetch list data
-PCore.getDataPageUtils().getDataAsync(dataPageName, context, params, paging, query, options);
-
-// Get page data (single record)
-PCore.getDataPageUtils().getPageDataAsync(dataPageName, context, params);
-```
+Fetch list data via `PCore.getDataPageUtils().getDataAsync(dataPageName, context, params, paging, query, options)`. Get a single-record page via `PCore.getDataPageUtils().getPageDataAsync(dataPageName, context, params)`.
 
 ### Case Info
 
-```typescript
-const pConn = getPConnect();
-const caseKey = pConn.getCaseInfo().getKey();
-const caseID = pConn.getCaseInfo().getID();
-const caseName = pConn.getCaseInfo().getName();
-```
+Call `getPConnect()` into `pConn`, then read `pConn.getCaseInfo().getKey()` for the case key, `pConn.getCaseInfo().getID()` for the case ID, and `pConn.getCaseInfo().getName()` for the case name.
 
 ### Attachments
 
-```typescript
-PCore.getAttachmentUtils().prepareAttachmentData(value);
-PCore.getAttachmentUtils().uploadAttachment(file, onProgress, errorHandler, context);
-PCore.getAttachmentUtils().downloadAttachment(attachmentID, context);
-```
+Use `PCore.getAttachmentUtils().prepareAttachmentData(value)` to prepare attachment data, `PCore.getAttachmentUtils().uploadAttachment(file, onProgress, errorHandler, context)` to upload, and `PCore.getAttachmentUtils().downloadAttachment(attachmentID, context)` to download.
 
 ### Actions
 
-```typescript
-const actionsApi = pConn.getActionsApi();
-actionsApi.updateFieldValue(propName, value);
-actionsApi.triggerFieldChange(propName, value);
-actionsApi.openLocalAction(actionName, options);
-```
+Resolve `actionsApi` via `pConn.getActionsApi()`, then use `actionsApi.updateFieldValue(propName, value)` to update a field's value, `actionsApi.triggerFieldChange(propName, value)` to trigger a field change event, and `actionsApi.openLocalAction(actionName, options)` to open a local action.
 
 ### Container Management
 
-```typescript
-const containerManager = pConn.getContainerManager();
-containerManager.addContainerItem({
-  semanticURL,
-  key,
-  flowName,
-  caseViewMode,
-  resourceType,
-  data,
-});
-```
+Resolve `containerManager` via `pConn.getContainerManager()`, then call `containerManager.addContainerItem({ semanticURL, key, flowName, caseViewMode, resourceType, data })` to add a container item.
 
 ---
 
 ## Registration
 
-Register widgets in `src/components/component-map.ts`:
-
-```typescript
-import MyWidget from './widget/MyWidget';
-
-// In getSampleComponentMap():
-{
-  ...sdkComponents,
-  MyWidget,  // Key must match the Pega component name
-}
-```
+Register widgets in the project's component map: import the widget's default export from its folder under the widget components directory, then add it to the object returned by the project's component registration function. The key must match the Pega component name.
 
 ---
 
@@ -242,19 +106,19 @@ import MyWidget from './widget/MyWidget';
 | FileUtility     | File management utility     | `PCore.getAttachmentUtils()`                                        |
 | Followers       | Case followers list         | `PCore.getDataPageUtils()`                                          |
 | QuickCreate     | Quick case creation buttons | `PCore.getMashupApi().createCase()`                                 |
-| SummaryItem     | Single summary card         | Props from parent                                                   |
-| SummaryList     | List of summary cards       | Props from parent                                                   |
+| SummaryItem     | Single summary card         | Inputs from parent                                                  |
+| SummaryList     | List of summary cards       | Inputs from parent                                                  |
 | ToDo            | Assignment worklist         | `PCore.getDataPageUtils()`, `PCore.getMashupApi().openAssignment()` |
 
 ---
 
 ## Key Conventions
 
-1. **Default export** — `export default function WidgetName`.
+1. **Default export** — Each component is exported as the module's default export.
 2. **Self-contained data** — Widgets fetch their own data (don't rely on parent passing data down).
 3. **Loading states** — Always handle loading/error states when fetching data.
-4. **PCore globals** — Access `PCore` directly (declared globally by `@pega/pcore-pconnect-typedefs`).
+4. **PCore globals** — Access `PCore` directly (declared globally by the Pega runtime type definitions).
 5. **Localization** — Use `pConn.getLocalizationService()` for translated strings when available.
 6. **Context** — Use `pConn.getContextName()` as the context parameter for data page calls.
-7. **Card layout** — Widgets typically render inside MUI `Card` with `CardHeader` and `CardContent`.
+7. **Card layout** — Widgets typically render inside the design system's card component with a header and content area.
 8. **Action handling** — Use `PCore.getMashupApi()` for case/assignment operations, `actionsApi` for field updates.

package/templates/react-sdk-reference/.ai-common/skills/widget-skills/AppAnnouncement.md

@@ -2,23 +2,23 @@
 
 Card-based announcement widget. Displays a system-wide or application announcement with an optional bullet list of items and a "See what's new" external link button.
 
-> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, props interface, data-fetching patterns, and registration conventions common to ALL widget components.
+> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, inputs interface, data-fetching patterns, and registration conventions common to ALL widget components.
 
 ---
 
 ## Component Purpose
 
-Renders an announcement card with a heading, description text, optional bullet list of items sourced from a `datasource` prop, and an optional external link button. Styled with a left accent border to visually distinguish it from other cards.
+Renders an announcement card with a heading, description text, optional bullet list of items sourced from a `datasource` input, and an optional external link button. Styled with a left accent border to visually distinguish it from other cards.
 
 ## Pega Metadata
 
-- **Registration key:** `AppAnnouncement` (in `component-map.ts`)
+- **Registration key:** `AppAnnouncement` (registered in the project's component map)
 - **Category:** Widget — informational display
-- **Extends:** `PConnProps`
+- **Extends:** the project's base component interface
 
-## Props
+## Inputs
 
-| Prop           | Type       | Required | Description                                                            |
+| Input          | Type       | Required | Description                                                            |
 | -------------- | ---------- | -------- | ---------------------------------------------------------------------- |
 | `header`       | `string`   | No       | Announcement card title                                                |
 | `description`  | `string`   | No       | Announcement body text                                                 |
@@ -26,49 +26,22 @@ Renders an announcement card with a heading, description text, optional bullet l
 | `whatsnewlink` | `string`   | No       | URL for the "See what's new" button; if absent, button is not rendered |
 | `getPConnect`  | `function` | Yes      | PConnect getter                                                        |
 
-## Component Skeleton
-
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-
-interface AppAnnouncementProps extends PConnProps {
-  header?: string;
-  description?: string;
-  datasource?: any;
-  whatsnewlink?: string;
-}
-
-export default function AppAnnouncement(props: AppAnnouncementProps) {
-  const { header = '', description = '', datasource = [], whatsnewlink = '' } = props;
-
-  // 1. Extract item names from datasource
-  const details = datasource?.source?.map(item => item.name) || [];
-
-  // 2. Render: Card with left accent border + vertical margin for sibling spacing
-  //    ⚠️ margin '0.5rem 0' is REQUIRED — without it the card has no top spacing
-  return (
-    <Card style={{ borderLeft: '6px solid var(--app-primary-light-color)', margin: '0.5rem 0' }}>
-      <CardHeader><h6>{header}</h6></CardHeader>
-      <CardContent>
-        <p>{description}</p>
-        {details.map((itm, idx) => <p key={idx}>- {itm}</p>)}
-      </CardContent>
-      {whatsnewlink && (
-        <CardActions>
-          <Button onClick={() => window.open(whatsnewlink, '_blank')}>See what's new</Button>
-        </CardActions>
-      )}
-    </Card>
-  );
-}
-```
+## Implementation Structure
+
+**Module Setup:** The component's inputs interface extends the project's base component interface with optional `header` (string), `description` (string), `datasource` (any), and `whatsnewlink` (string).
+
+**Main Component Logic** — steps in order:
+
+1. Receive `header`, `description`, `datasource`, and `whatsnewlink` from inputs, each defaulting to an empty string (`datasource` defaulting to an empty array).
+2. Extract item names from `datasource`: map `datasource?.source` to an array of each item's `name` property, defaulting to an empty array when `datasource.source` is absent.
+3. Render a card with a left accent border (6px solid, using the primary light color token) and vertical margin (`0.5rem 0` top/bottom) so the card has proper spacing from sibling elements — this margin is required, without it the card has no top spacing. Inside, render a card header containing the `header` text as a heading, followed by a card content block containing the `description` paragraph and one paragraph per extracted item name (prefixed with a dash). When `whatsnewlink` is non-empty, render a card actions block with a button labeled "See what's new" that opens `whatsnewlink` in a new browser tab on click.
 
 ## Behavioral Contract
 
 1. **Item list extraction:** If `datasource` is provided and `datasource.source` is a non-empty array, extract item names and render them as a bullet list. Each array item is expected to have a `name` property.
 2. **Button:** If `whatsnewlink` is non-empty, render a button labeled `"See what's new"` (or localized equivalent). On click, open the URL in a new browser tab (`window.open(whatsnewlink, '_blank')`).
 3. **Description:** Render the `description` string as plain text below the header.
-4. **No data fetching:** This widget is purely prop-driven — it does not call any PCore data APIs.
+4. **No data fetching:** This widget is purely input-driven — it does not call any PCore data APIs.
 
 ## Visual Specifications
 
@@ -77,7 +50,7 @@ export default function AppAnnouncement(props: AppAnnouncementProps) {
 | Element                 | Position                                |
 | ----------------------- | --------------------------------------- |
 | Left accent border      | 6px solid, primary light color          |
-| Card header             | `header` prop as title                  |
+| Card header             | `header` input as title                 |
 | Card content            | Description text + optional bullet list |
 | "See what's new" button | Below description / bullet list         |
 
@@ -91,31 +64,31 @@ export default function AppAnnouncement(props: AppAnnouncementProps) {
 
 ## Edge Cases & Special Logic
 
-- `datasource` may be `undefined` or `datasource.source` may be an empty array — in both cases, render no bullet list (not even an empty `<ul>`).
+- `datasource` may be `undefined` or `datasource.source` may be an empty array — in both cases, render no bullet list.
 - `whatsnewlink` may be an empty string — treat the same as absent (no button rendered).
 - `header` and `description` may both be absent — render the card with empty/placeholder content without crashing.
 - Item objects in `datasource.source` are expected to have `name` — guard against items where `name` is `undefined`.
 
 ## Dependencies
 
-- MUI: `<Card>`, `<CardHeader>`, `<CardContent>`, `<Typography>`, `<Button>`
+- The design system's card component (with header, content, and actions regions)
+- The design system's typography component
+- The design system's button component
 
 ## Design System Mapping
 
 **UI control type:** Announcement / informational card with bullet list and external link.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Card                                        | Bullet List                   | Button                     |
-| ------------------ | ------------------------------------------- | ----------------------------- | -------------------------- |
-| Default (CSS only) | `<div>` with left border + box-shadow       | `<ul>/<li>`                   | `<button>` opening new tab |
-| MUI                | `<Card>` + `<CardHeader>` + `<CardContent>` | `<List>/<ListItem>` or `<ul>` | `<Button>`                 |
-| Ant Design         | `<Card>` with `title` prop                  | `<ul>/<li>`                   | `<Button>`                 |
-| Chakra UI          | `<Card>` + `<CardHeader>` + `<CardBody>`    | `<UnorderedList>/<ListItem>`  | `<Button>`                 |
-| Shadcn/ui          | `<Card>` + `<CardHeader>` + `<CardContent>` | `<ul>/<li>`                   | `<Button>`                 |
+- **Card container:** A card component with distinct header, content, and footer/actions regions. Apply a 6px solid left accent border using the primary light color token — this is the key visual identifier.
+- **Card header:** Renders the `header` text as a heading-level element (typically h6 weight).
+- **Card content:** Contains the `description` as body text, followed by the optional bullet list (one item per line, prefixed with a dash or rendered as a standard unordered list).
+- **Card actions / footer:** Contains the "See what's new" button. This button must open the URL in a new tab with appropriate security attributes.
+- **Button:** A primary-colored text or outlined button with no text transformation (no uppercase).
 
-When implementing in a specific design system:
+Implementation notes:
 
 - Left accent border is a key visual identifier — implement it via CSS or the design system's border utilities
-- "See what's new" must open in a new tab (`target='_blank'` + `rel='noopener noreferrer'`)
-- The widget is entirely prop-driven — no data fetching needed
+- "See what's new" must open in a new tab with `rel='noopener noreferrer'`
+- The widget is entirely input-driven — no data fetching needed