@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/WideNarrow.mdrules

@@ -0,0 +1,155 @@
+---
+description: Template component skill: WideNarrow
+alwaysApply: false
+---
+
+# Skill: WideNarrow
+
+Asymmetric two-column layout with a wide left column (~67%) and a narrow right column (~33%). Mirror of NarrowWide. Includes four sub-variants.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders two children side by side with the left column wider than the right. Typically used when the main content occupies the left and a utility/sidebar panel sits on the right. Four sub-variants:
+
+- **`WideNarrow`** — core CSS-based layout, accepts either `a`/`b` slot props or React `children[0]`/`children[1]`
+- **`WideNarrowPage`** — wrapper that passes React children as `a` and `b` slot props to `WideNarrow`
+- **`WideNarrowForm`** — simplified wrapper using only `children`
+- **`WideNarrowDetails`** — details read-only variant; sets children to DISPLAY_ONLY mode and supports highlighted data
+
+> This component is the mirror of `NarrowWide`. All behavioral and structural patterns are identical except column order and CSS class names. See the `NarrowWide` skill for detailed pattern descriptions.
+
+## Pega Metadata
+
+| Variant | Registration Key |
+|---------|-----------------|
+| WideNarrow | `WideNarrow` |
+| WideNarrowPage | `WideNarrowPage` |
+| WideNarrowForm | `WideNarrowForm` |
+| WideNarrowDetails | `WideNarrowDetails` |
+
+All extend `PConnProps`.
+
+## Props
+
+### WideNarrow
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | No | Two children — `[0]` → wide (left), `[1]` → narrow (right) |
+| `a` | `any` | No | Wide (left) column content |
+| `b` | `any` | No | Narrow (right) column content |
+| `title` | `string` | No | Optional title (not rendered) |
+| `cols` | `string` | No | Column template (not rendered) |
+| `icon` | `string` | No | Icon name (not rendered) |
+
+### WideNarrowPage
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Two children — `[0]` → wide slot, `[1]` → narrow slot |
+| `title` | `string` | Yes | Page title (passed to WideNarrow) |
+| `templateCol` | `string` | No | Column ratio (default `'1fr 1fr'`) |
+| `icon` | `string` | No | Icon name (strips `'pi pi-'` prefix) |
+
+### WideNarrowForm
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode[]` | Yes | Two children rendered in wide/narrow slots |
+
+### WideNarrowDetails
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | No | Section label for FieldGroup |
+| `showLabel` | `boolean` | No | Whether to show the label. Default `true` |
+| `showHighlightedData` | `boolean` | No | Whether to render highlighted data fields. Default `false` |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### WideNarrow
+
+1. If `children` is provided and has exactly 2 items: render `children[0]` in `.psdk-wide-column-column` and `children[1]` in `.psdk-narrow-column-column` (both wrapped in `.psdk-wide-narrow-column`).
+2. If `a` and `b` are provided: render `a` in the wide slot and `b` in the narrow slot.
+3. `children` takes priority over `a`/`b` when both are present.
+
+### WideNarrowPage
+
+1. Extract `childArray = Children.toArray(children)`.
+2. Retrieve `WideNarrow` from the component registry.
+3. Render `<WideNarrow a={childArray[0]} b={childArray[1]} title={title} cols={templateCol} icon={icon?.replace('pi pi-', '')} />`.
+
+### WideNarrowForm
+
+1. Render using `children` path — checks `children.length === 2`, renders wide/narrow CSS divs.
+
+### WideNarrowDetails
+
+1. Set `getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `setInheritedProp('readOnly', true)`.
+2. Map `getPConnect().getChildren()` → `createElement(PConnectComponent, { ...configObject, key: index })`.
+3. If `showHighlightedData` is true, read `getRawMetadata().config.highlightedData`, set each field's `displayMode = 'STACKED_LARGE_VAL'`, mark `pyStatusWork` as `displayAsStatus=true`, and create components via `getPConnect().createComponent(field, '', 0, {})`.
+4. Wrap in `<FieldGroup name={theName}>` using `propsToUse.showLabel && propsToUse.label`.
+5. Layout: highlighted data in `Grid size={{ xs: COLUMN_WIDTHS[i] }}` where **`COLUMN_WIDTHS = [8, 4]`** (wide left, narrow right — reversed vs NarrowWideDetails).
+6. Children rendered in `Grid size={{ xs: 12 }}` rows.
+
+## Visual Specifications
+
+Derived from `WideNarrow.css`:
+
+### Container
+
+| CSS Class | Property | Value |
+|-----------|----------|-------|
+| `.psdk-wide-narrow-column` | Display | two-column row layout |
+| `.psdk-wide-column-column` | Width | ~67% (2 of 3 parts) — LEFT column |
+| `.psdk-narrow-column-column` | Width | ~33% (1 of 3 parts) — RIGHT column |
+
+**CSS-only implementation notes:**
+- `.psdk-wide-narrow-column`: `display: grid; grid-template-columns: 2fr 1fr; gap: 1rem`.
+- Wide column (left): `2fr` — takes the first grid column.
+- Narrow column (right): `1fr` — takes the second grid column.
+- On mobile: `grid-template-columns: 1fr` (stacks vertically, wide on top).
+
+### Key Difference from NarrowWide
+
+| | NarrowWide | WideNarrow |
+|---|---|---|
+| Left column | Narrow (~33%) | Wide (~67%) |
+| Right column | Wide (~67%) | Narrow (~33%) |
+| CSS container class | `.psdk-narrow-wide-column` | `.psdk-wide-narrow-column` |
+| `COLUMN_WIDTHS` (Details) | `[4, 8]` | `[8, 4]` |
+
+## Edge Cases & Special Logic
+
+- `WideNarrowDetails` defaults `children` to empty (`= []`) — safe even if no children are provided.
+- Highlighted data guard: check `if (!theConfigObject) theConfigObject = {}` before creating PConnectComponent — prevents crash on null config objects.
+- Icon cleanup in `WideNarrowPage`: strip `'pi pi-'` from icon string before passing to `WideNarrow`.
+
+## Dependencies
+
+- `WideNarrowPage`: `getComponentFromRegistry` from `@pega/sdk-react`
+- `WideNarrowDetails`: `getComponentFromRegistry('FieldGroup')`, `PConnectComponent` from `@pega/sdk-react`
+
+## Design System Mapping
+
+**UI control type:** Asymmetric two-column layout (main content + sidebar).
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | CSS Grid `grid-template-columns: 2fr 1fr; gap: 1rem` |
+| MUI | `<Grid container><Grid size={{ xs: 12, md: 8 }}><Grid size={{ xs: 12, md: 4 }}>` |
+| Ant Design | `<Row gutter={16}><Col xs={24} md={16}><Col xs={24} md={8}>` |
+| Chakra UI | `<Grid templateColumns={{ base: '1fr', md: '2fr 1fr' }} gap={4}>` |
+| Shadcn/ui | Tailwind `grid grid-cols-1 md:grid-cols-[2fr_1fr] gap-4` |
+
+When implementing in a specific design system:
+- Wide column ≈ 67% width (left side)
+- Narrow column ≈ 33% width (right side)
+- `WideNarrowDetails` forces DISPLAY_ONLY + readOnly on all children

package/templates/react-sdk-reference/.cursor/rules/skills/template-skills/WssNavBar.mdrules

@@ -0,0 +1,140 @@
+---
+description: Template component skill: WssNavBar
+alwaysApply: false
+---
+
+# Skill: WssNavBar
+
+WSS (Web Self-Service) navigation bar template. Renders the app bar for WSS portal with responsive hamburger menu, navigation links, operator avatar, and logout.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Provides the top navigation bar for WSS (Web Self-Service) portals. Responsive: shows a hamburger menu on mobile, full nav links on desktop. Navigation position and alignment are configurable. Includes operator avatar with initials and a logout action.
+
+## Pega Metadata
+
+- **Registration key:** `WssNavBar` (in `component-map.ts`)
+- **Category:** Navigation template — WSS portal
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `links` | `array` | Yes | Array of `{ label, url, id }` navigation link objects |
+| `navDisplayOptions` | `object` | No | `{ alignment: 'left'|'right'|'center', position: 'inline'|'below' }` |
+| `portalLogoUrl` | `string` | No | URL for the portal logo image |
+| `operatorInfo` | `object` | No | `{ displayName: string }` — for avatar initials |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## Behavioral Contract
+
+### Responsive Layout
+
+- **Mobile (xs breakpoint):** Hamburger menu button (`<MenuIcon>`) shown; nav links hidden.
+  - On click: opens a `<Drawer>` or dropdown menu with nav links.
+  - CSS: `display: { xs: 'flex', md: 'none' }` on hamburger; `display: { xs: 'none', md: 'flex' }` on nav links.
+- **Desktop (md+ breakpoint):** Nav links shown inline; hamburger hidden.
+
+### Navigation Position
+
+From `navDisplayOptions.position`:
+- `'inline'` — nav links appear in the same row as the logo.
+- `'below'` — nav links appear in a second row below the logo/title row.
+
+### Navigation Alignment
+
+From `navDisplayOptions.alignment`:
+- `'left'` — links flush left.
+- `'right'` — links pushed to the right (flex with `ml: 'auto'`).
+- `'center'` — links centered.
+
+### Operator Avatar
+
+- Extract initials from `operatorInfo.displayName`:
+  - Split by space, take first letter of first and last word.
+  - E.g. `"John Smith"` → `"JS"`.
+- Render as `<Avatar>{initials}</Avatar>`.
+- Clicking avatar opens a menu with a Logout option.
+
+### Logout
+
+- Import `logout` from `@pega/auth/lib/sdk-auth-manager`.
+- Call `logout()` when the Logout menu item is clicked.
+
+### Render Structure
+
+```
+<AppBar position='static'>
+  <Toolbar>
+    {/* Logo */}
+    {portalLogoUrl && <img src={portalLogoUrl} alt='logo' />}
+
+    {/* Hamburger (mobile) */}
+    <IconButton sx={{ display: { xs: 'flex', md: 'none' } }} onClick={openMobileMenu}>
+      <MenuIcon />
+    </IconButton>
+
+    {/* Nav links (desktop) */}
+    <Box sx={{ display: { xs: 'none', md: 'flex' }, ...alignmentStyles }}>
+      {links.map(link => <Button key={link.id} href={link.url}>{link.label}</Button>)}
+    </Box>
+
+    {/* Operator avatar */}
+    <Avatar onClick={openUserMenu}>{initials}</Avatar>
+  </Toolbar>
+</AppBar>
+```
+
+## Visual Specifications
+
+| Element | Mobile | Desktop |
+|---------|--------|---------|
+| Logo | Shown | Shown |
+| Nav links | Hidden (hamburger menu) | Shown inline or below |
+| Avatar | Shown | Shown |
+| Hamburger | Shown | Hidden |
+
+**CSS-only implementation notes:**
+- App bar: `background: var(--app-primary-color); color: white`.
+- Toolbar: `display: flex; align-items: center; gap: 1rem; padding: 0 1rem`.
+- Hamburger: `display: none`. At mobile breakpoint: `display: flex`.
+- Nav links: `display: flex; gap: 0.5rem`. At mobile breakpoint: `display: none`.
+- Avatar: `width: 36px; height: 36px; border-radius: 50%; background: var(--avatar-bg); cursor: pointer`.
+- Logout menu: `position: absolute; top: 100%; right: 0; background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.2)`.
+
+## Edge Cases & Special Logic
+
+- `portalLogoUrl` is async — show fallback text until resolved.
+- `operatorInfo.displayName` may be undefined — guard and show a default avatar (single letter or icon).
+- `navDisplayOptions` may be absent — default to `{ alignment: 'left', position: 'inline' }`.
+- Mobile drawer state must be managed separately from the user menu state.
+
+## Dependencies
+
+- `logout` from `@pega/auth/lib/sdk-auth-manager` — logout handler
+- MUI: `<AppBar>`, `<Toolbar>`, `<IconButton>`, `<Avatar>`, `<Menu>`, `<MenuItem>`, `<Button>`, `<Box>`
+- MUI Icons: `<MenuIcon>`
+
+## Design System Mapping
+
+**UI control type:** Responsive application navigation bar with avatar and logout.
+
+Listed design systems are examples only.
+
+| Design System | App Bar | Avatar | Mobile Menu |
+|---|---|---|---|
+| Default (CSS only) | `<header>` + CSS | `<div class='avatar'>` | CSS hamburger + dropdown |
+| MUI | `<AppBar>` + `<Toolbar>` | `<Avatar>` | `<Drawer>` or `<Menu>` |
+| Ant Design | `<Layout.Header>` | `<Avatar>` | `<Drawer>` |
+| Chakra UI | `<Box as='header'>` | `<Avatar>` | `<Drawer>` |
+| Shadcn/ui | Custom `<header>` | Custom initials avatar | `<Sheet>` (drawer) |
+
+When implementing in a specific design system:
+- `logout` from `@pega/auth/lib/sdk-auth-manager` is mandatory — always call the SDK logout, not a custom one
+- Responsive breakpoints for hamburger/nav visibility must be implemented
+- `navDisplayOptions.alignment` and `.position` must be respected

package/templates/react-sdk-reference/.cursor/rules/skills/widget-components.mdrules

@@ -0,0 +1,276 @@
+---
+description: widget-components
+alwaysApply: false
+---
+
+# 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.).
+
+---
+
+## 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)
+```
+
+---
+
+## Props Interface
+
+Widget components extend `PConnProps`:
+
+```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;
+}
+```
+
+---
+
+## Implementation Pattern
+
+### 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>
+  );
+}
+```
+
+---
+
+## Design System Adaptation
+
+The PCore data-fetching logic (all `PCore.*` calls) is always identical regardless of design system. Only the `// [DS RENDER]` section changes.
+
+**1. Check the component-specific skill file** — `.cursor/rules/skills/widget-skills/<ComponentName>.mdrules` 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 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>
+```
+
+**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>` |
+
+**5. Icons** — if the DS has a companion icon package, read 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);
+}
+```
+
+---
+
+## Common Pega APIs Used in Widgets
+
+### 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);
+```
+
+### Case Info
+
+```typescript
+const pConn = getPConnect();
+const caseKey = pConn.getCaseInfo().getKey();
+const caseID = pConn.getCaseInfo().getID();
+const caseName = pConn.getCaseInfo().getName();
+```
+
+### Attachments
+
+```typescript
+PCore.getAttachmentUtils().prepareAttachmentData(value);
+PCore.getAttachmentUtils().uploadAttachment(
+  file,
+  onProgress,
+  errorHandler,
+  context,
+);
+PCore.getAttachmentUtils().downloadAttachment(attachmentID, context);
+```
+
+### Actions
+
+```typescript
+const actionsApi = pConn.getActionsApi();
+actionsApi.updateFieldValue(propName, value);
+actionsApi.triggerFieldChange(propName, value);
+actionsApi.openLocalAction(actionName, options);
+```
+
+### Container Management
+
+```typescript
+const containerManager = pConn.getContainerManager();
+containerManager.addContainerItem({
+  semanticURL,
+  key,
+  flowName,
+  caseViewMode,
+  resourceType,
+  data,
+});
+```
+
+---
+
+## 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
+}
+```
+
+---
+
+## Existing Widget Components
+
+| Component       | Description                 | Key APIs                                                            |
+| --------------- | --------------------------- | ------------------------------------------------------------------- |
+| AppAnnouncement | System-wide announcements   | `PCore.getMessagingServiceUtils()`                                  |
+| Attachment      | File upload/download        | `PCore.getAttachmentUtils()`                                        |
+| CaseHistory     | Case audit trail            | `PCore.getDataPageUtils()`                                          |
+| 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                                                   |
+| ToDo            | Assignment worklist         | `PCore.getDataPageUtils()`, `PCore.getMashupApi().openAssignment()` |
+
+---
+
+## Key Conventions
+
+1. **Default export** — `export default function WidgetName`.
+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`).
+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`.
+8. **Action handling** — Use `PCore.getMashupApi()` for case/assignment operations, `actionsApi` for field updates.

package/templates/react-sdk-reference/.cursor/rules/skills/widget-skills/AppAnnouncement.mdrules

@@ -0,0 +1,87 @@
+---
+description: Widget component skill: AppAnnouncement
+alwaysApply: false
+---
+
+# Skill: AppAnnouncement
+
+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.
+
+---
+
+## 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.
+
+## Pega Metadata
+
+- **Registration key:** `AppAnnouncement` (in `component-map.ts`)
+- **Category:** Widget — informational display
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `header` | `string` | No | Announcement card title |
+| `description` | `string` | No | Announcement body text |
+| `datasource` | `object` | No | Data source object — `datasource.source` is an array of item objects |
+| `whatsnewlink` | `string` | No | URL for the "See what's new" button; if absent, button is not rendered |
+| `getPConnect` | `function` | Yes | PConnect getter |
+
+## 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.
+
+## Visual Specifications
+
+### Card Layout
+
+| Element | Position |
+|---------|----------|
+| Left accent border | 6px solid, primary light color |
+| Card header | `header` prop as title |
+| Card content | Description text + optional bullet list |
+| "See what's new" button | Below description / bullet list |
+
+**CSS-only implementation notes:**
+- Card: `border-left: 6px solid var(--app-primary-light-color); border-radius: 4px; box-shadow: 0 1px 4px rgba(0,0,0,0.12)`.
+- Card header: `padding: 12px 16px; font-weight: 600`.
+- Card content: `padding: 0 16px 16px`.
+- Bullet list: `padding-left: 1.5rem; margin: 0.5rem 0`.
+- "See what's new" button: `margin-top: 0.75rem; text-transform: none`.
+
+## 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>`).
+- `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>`
+
+## Design System Mapping
+
+**UI control type:** Announcement / informational card with bullet list and external link.
+
+Listed design systems are examples only.
+
+| 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>` |
+
+When implementing in a specific design system:
+- 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