@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.github/skills/widget-skills/Attachment.md

@@ -1,151 +0,0 @@
-# Skill: Attachment
-
-File upload/download widget for case attachments. Behaves like a form field — binds to a case attachment property, supports multiple files, validates extensions and size, tracks upload progress, and blocks form submission during active uploads.
-
-> **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 a file attachment control within a Pega form. Users can upload one or multiple files, download existing attachments, and delete attachments. The widget validates file extensions and enforces a maximum size from environment config. Upload progress is shown per-file. Form submission is blocked while uploads are in progress via the action sequencer.
-
-## Pega Metadata
-
-- **Registration key:** `Attachment` (in `component-map.ts`)
-- **Category:** Widget — form field (file input)
-- **Extends:** `Omit<PConnFieldProps, 'value'>` (uses `value: any` instead of the standard string value)
-
-## Props
-
-| Prop               | Type                | Required                   | Description                                                                  |
-| ------------------ | ------------------- | -------------------------- | ---------------------------------------------------------------------------- |
-| `value`            | `any`               | Yes                        | Attachment list or single attachment object (from Pega property)             |
-| `allowMultiple`    | `boolean \| string` | No                         | Whether multiple files can be attached. Default `false`                      |
-| `extensions`       | `string`            | No                         | Comma-separated list of allowed file extensions (e.g., `".pdf,.doc,.jpg"`)   |
-| `editMode`         | `string`            | No                         | `"tableRows"` for inline table edit mode (special multi-attachment handling) |
-| `isTableFormatter` | `boolean`           | No                         | Whether this widget is used inside a table formatter                         |
-| `label`            | `string`            | Yes (from PConnFieldProps) | Field label                                                                  |
-| `required`         | `boolean`           | No                         | Whether a file is required                                                   |
-| `disabled`         | `boolean`           | No                         | Whether the control is disabled                                              |
-| `displayMode`      | `string`            | No                         | `"DISPLAY_ONLY"` for read-only rendering                                     |
-| `validatemessage`  | `string`            | No                         | Validation error message to display                                          |
-| `helperText`       | `string`            | No                         | Helper text shown below the control                                          |
-| `getPConnect`      | `function`          | Yes                        | PConnect getter                                                              |
-
-## Behavioral Contract
-
-### Attachment Format Detection
-
-Pega has two attachment data formats — detect which one is in use:
-
-**Old format (annotation-based):**
-
-```typescript
-value = { pxResults: [...], pyAttachCount: N }
-```
-
-**New standard format:**
-
-```typescript
-value = [{ ID, name, mimeType, category, ... }]  // array
-```
-
-Call `PCore.getAttachmentUtils().prepareAttachmentData(value)` to normalize both formats into a unified `FileObject[]` array.
-
-### File Validation
-
-On file selection (via `<input type='file'>`):
-
-1. **Extension check:** Compare selected file's extension against `extensions` prop (split by comma). If not allowed, add an error to the file and do not upload.
-2. **Size check:** Compare file size against `PCore.getEnvironmentInfo().getMaxAttachmentSize()` (in bytes). If too large, add a size error.
-3. Valid files proceed to upload.
-
-### Upload Flow
-
-1. Call `PCore.getActionsSequencer().addAction('attachment_upload_' + fileId)` — blocks form submission.
-2. Call `PCore.getAttachmentUtils().uploadAttachment(file, onProgress, onError, context)`.
-3. On progress: update per-file `progress` value (0–100) in state.
-4. On success: add the returned attachment metadata to the local file list; update the Pega property via `pConn.setReferenceList(newAttachmentList)`.
-5. Call `PCore.getActionsSequencer().removeAction('attachment_upload_' + fileId)` — unblocks form submission.
-6. On error: set file error state; call `PCore.getMessageManager().addMessages([errorMessage])`.
-
-### Download
-
-Call `PCore.getAttachmentUtils().downloadAttachment(attachmentID, context)` — triggers browser file download.
-
-### Delete
-
-Remove the attachment from the local list and update `pConn.setReferenceList(updatedList)`. Do not call a separate delete API in the reference implementation — deletion is committed on form save.
-
-### Pub-Sub: Assignment Submission
-
-Subscribe to `PCore.getPubSubUtils().subscribe(BEFORE_ASSIGNMENT_SUBMIT, handleBeforeSubmit, 'Attachment')`. In `handleBeforeSubmit`, validate that no uploads are still in progress.
-
-### Read-Only Mode (`displayMode === 'DISPLAY_ONLY'`)
-
-Render a list of existing attachments as download links. No upload controls shown.
-
-### Inline Table Edit Mode (`editMode === 'tableRows'`)
-
-Compressed display for use inside a table cell. Show attachment count and a small upload button. Clicking opens a minimal upload dialog.
-
-## Visual Specifications
-
-| Element                   | Description                                                                           |
-| ------------------------- | ------------------------------------------------------------------------------------- |
-| Label                     | Standard field label above the control                                                |
-| Drop zone / Upload button | Clickable area to select files; optionally supports drag-and-drop                     |
-| File list                 | Each uploaded file: icon + name + size + progress bar (during upload) + delete button |
-| Error state               | Red error text below the control for invalid files or upload failures                 |
-| Helper text               | Secondary text below the control                                                      |
-
-**CSS-only implementation notes:**
-
-- Drop zone: `border: 2px dashed var(--border-color); border-radius: 4px; padding: 1rem; text-align: center; cursor: pointer`.
-- Drop zone hover: `border-color: var(--app-primary-color); background: var(--hover-bg)`.
-- File row: `display: flex; align-items: center; gap: 0.5rem; padding: 4px 0`.
-- Progress bar: `height: 4px; background: var(--app-primary-color); border-radius: 2px; transition: width 0.2s`.
-- Error text: `color: var(--error-color); font-size: 0.75rem; margin-top: 4px`.
-- Delete button: `color: var(--error-color)`.
-
-## Edge Cases & Special Logic
-
-- `allowMultiple` may be a string `"true"` / `"false"` or a boolean — always coerce: `allowMultiple === true || allowMultiple === 'true'`.
-- Upload progress: track per-file progress in a `Map<fileId, number>` state object.
-- `isTableFormatter`: when `true`, hide the label and reduce padding for compact table display.
-- Concurrent uploads: multiple files may upload simultaneously — the sequencer action must be keyed per-file.
-- Max size: call `PCore.getEnvironmentInfo().getMaxAttachmentSize()` at validation time (not at mount) — size config may be dynamic.
-- `extensions` may be empty string — if empty, allow all file types.
-
-## Dependencies
-
-- `AttachmentUtils.ts` — `validateExtension`, `validateSize`, `getFileTypeIcon`, `buildDownloadURL`, error handling helpers
-- `Attachment.types.ts` — `FileObject`, `AttachmentLinks`, `PageInstructionOptions` type definitions
-- `PCore.getAttachmentUtils()` — upload, download, prepareAttachmentData
-- `PCore.getActionsSequencer()` — block/unblock form submission during upload
-- `PCore.getEnvironmentInfo()` — max attachment size
-- `PCore.getMessageManager()` — error message display
-- `PCore.getPubSubUtils()` — before-submit subscription
-- `downloadjs` library — browser file download trigger
-
-## Design System Mapping
-
-**UI control type:** File upload form field with progress tracking, validation, and attachment list.
-
-Listed design systems are examples only.
-
-| Design System      | File Input                                         | Progress                        | File List                 |
-| ------------------ | -------------------------------------------------- | ------------------------------- | ------------------------- |
-| Default (CSS only) | `<input type='file'>` + custom styled drop zone    | `<progress>` element or CSS bar | `<ul>/<li>` rows          |
-| MUI                | Custom styled `<Box>` drop zone + hidden `<input>` | `<LinearProgress>`              | `<List>/<ListItem>`       |
-| Ant Design         | `<Upload dragger>`                                 | `<Progress>`                    | Built-in upload file list |
-| Chakra UI          | Custom `<Box>` with `useDropzone`                  | `<Progress>`                    | `<VStack>` rows           |
-| Shadcn/ui          | Custom drop zone                                   | Custom CSS progress bar         | `<ul>/<li>` rows          |
-
-When implementing in a specific design system:
-
-- Action sequencer blocking (`addAction`/`removeAction`) is mandatory — do not skip it; form submission must be blocked during uploads
-- Detect and normalize both old and new attachment formats via `prepareAttachmentData`
-- `allowMultiple` coercion (string vs boolean) is required
-- Extension and size validation must happen client-side before calling the upload API

package/templates/react-sdk-reference/.github/skills/widget-skills/CaseHistory.md

@@ -1,110 +0,0 @@
-# Skill: CaseHistory
-
-Case history widget. Fetches and displays the full audit trail for the current case in a table with Date, Description, and Performer columns.
-
-> **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 a table of case events sourced from the `D_pyWorkHistory` data page. Shows when each event happened (`pyUpdatedDateTime`), what happened (`pyMessageKey`), and who performed it (`pyPerformer`). Uses `fast-deep-equal` to skip unnecessary re-renders when data has not changed.
-
-## Pega Metadata
-
-- **Registration key:** `CaseHistory` (in `component-map.ts`)
-- **Category:** Widget — case data display
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop          | Type       | Required | Description                                           |
-| ------------- | ---------- | -------- | ----------------------------------------------------- |
-| `getPConnect` | `function` | Yes      | PConnect getter — used to resolve case ID and context |
-
-No additional custom props. All data is fetched internally.
-
-## Behavioral Contract
-
-### Data Fetch
-
-On mount, fetch history from the `D_pyWorkHistory` data page:
-
-```
-PCore.getDataApiUtils().getData(
-  'D_pyWorkHistory',
-  { pyCaseInsKey: caseKey },
-  context
-)
-```
-
-- `caseKey` = `pConn.getCaseInfo().getKey()` (the fully-qualified case key).
-- `context` = `pConn.getContextName()`.
-- Store result in `historyData` state array.
-- On error or empty response, `historyData` stays as `[]`.
-
-### Re-render Optimization
-
-Use `fast-deep-equal/react` to compare new `historyData` with previous value — only call `setHistoryData` if the data has actually changed. This prevents unnecessary re-renders caused by reference inequality.
-
-### Data Transformation
-
-For each history row, map:
-
-- **Date column:** Format `pyUpdatedDateTime` using the SDK date formatter (e.g., `formatDateTime(row.pyUpdatedDateTime)`) or display as-is.
-- **Description column:** `row.pyMessageKey` — the localized event description string.
-- **Performer column:** `row.pyPerformer` — the operator who performed the action.
-- Missing values: display `"---"` for any undefined/null field.
-
-## Visual Specifications
-
-### Table Layout
-
-| Column      | Field                           | Width |
-| ----------- | ------------------------------- | ----- |
-| Date        | `pyUpdatedDateTime` (formatted) | ~25%  |
-| Description | `pyMessageKey`                  | ~50%  |
-| Performer   | `pyPerformer`                   | ~25%  |
-
-**CSS-only implementation notes:**
-
-- Table container: `width: 100%; overflow-x: auto`.
-- Table: `border-collapse: collapse; width: 100%`.
-- Header cells: `background: var(--table-header-bg); font-weight: 600; padding: 8px 12px; border-bottom: 2px solid var(--divider-color)`.
-- Body cells: `padding: 8px 12px; border-bottom: 1px solid var(--divider-color)`.
-- Missing value placeholder `"---"`: `color: var(--secondary-text-color)`.
-- No pagination in the reference implementation — all rows shown.
-
-## Edge Cases & Special Logic
-
-- `D_pyWorkHistory` may return an empty array for cases with no history events — render an empty table body (or an empty-state message like `"No history available"`).
-- `pyUpdatedDateTime` format varies — always run it through the SDK date formatter before display.
-- `pyMessageKey` may be a locale key — resolve it via `PCore.getLocaleUtils().getLocaleValue()` if a localized string is required.
-- The widget has no pagination — for cases with very long history, the table may become very tall. Consider adding pagination if needed.
-
-## Dependencies
-
-- `PCore.getDataApiUtils().getData()` — fetches `D_pyWorkHistory` data page
-- `fast-deep-equal/react` — prevents unnecessary re-renders
-- `PCore.getConstants().CASE_INFO.CASE_INFO_ID` — resolves case ID constant
-- MUI: `<Table>`, `<TableBody>`, `<TableCell>`, `<TableContainer>`, `<TableHead>`, `<TableRow>`
-
-## Design System Mapping
-
-**UI control type:** Read-only case audit table with 3 columns.
-
-Listed design systems are examples only.
-
-| Design System      | Table                                                                             |
-| ------------------ | --------------------------------------------------------------------------------- |
-| Default (CSS only) | `<table>/<thead>/<tbody>/<tr>/<td>`                                               |
-| MUI                | `<TableContainer>` + `<Table>` + `<TableHead>/<TableBody>/<TableRow>/<TableCell>` |
-| Ant Design         | `<Table dataSource={historyData} columns={...}>`                                  |
-| Chakra UI          | `<Table>` + `<Thead>/<Tbody>/<Tr>/<Th>/<Td>`                                      |
-| Shadcn/ui          | `<Table>` + `<TableHeader>/<TableBody>/<TableRow>/<TableHead>/<TableCell>`        |
-
-When implementing in a specific design system:
-
-- `fast-deep-equal` comparison is a performance optimization — include it to avoid redundant renders on re-subscription
-- Data page name `D_pyWorkHistory` is fixed — do not make it configurable
-- Missing field fallback `"---"` should be consistent across all three columns

package/templates/react-sdk-reference/.github/skills/widget-skills/Followers.md

@@ -1,103 +0,0 @@
-# Skill: Followers
-
-Followers widget. Displays the list of users following the current case. Currently a stub/placeholder in the reference implementation — renders an "unsupported" message.
-
-> **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
-
-Intended to display the list of operators following a case, allowing users to follow/unfollow a case and see who else is following it. The reference implementation is a **stub** — it renders a `"Followers - unsupported"` message inside a card. A full implementation would fetch follower data from the Pega data layer and provide follow/unfollow actions.
-
-## Pega Metadata
-
-- **Registration key:** `Followers` (in `component-map.ts`)
-- **Category:** Widget — social / collaboration
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop          | Type       | Required | Description     |
-| ------------- | ---------- | -------- | --------------- |
-| `getPConnect` | `function` | Yes      | PConnect getter |
-
-No additional custom props in the current stub implementation. A full implementation would likely include:
-
-- `datasource` — data page name for follower list
-- `headerText` — widget title (e.g., `"Followers"`)
-
-## Behavioral Contract
-
-### Current (Stub) Implementation
-
-1. Render a `<Card>` with title `"Followers"`.
-2. Show `"Followers - unsupported"` body text.
-3. No data fetching, no actions.
-
-### Expected Full Implementation
-
-1. **Fetch followers:** Call `PCore.getDataPageUtils().getDataAsync('D_pyCaseFollowers', context, { caseKey })` on mount.
-2. **Display follower list:** Render each follower's avatar (initials) and display name.
-3. **Follow/unfollow toggle:** Button to follow or unfollow the current case:
-   - Follow: `PCore.getRestClient().invokeCustomRestApi('/api/v1/cases/{caseID}/followers', { method: 'POST', ... })`.
-   - Unfollow: same endpoint with `DELETE` method.
-4. **Real-time update:** Subscribe to follower change events via pub-sub if available.
-
-## Visual Specifications
-
-### Stub Rendering
-
-| Element    | Value                                  |
-| ---------- | -------------------------------------- |
-| Card title | `"Followers"`                          |
-| Card body  | `"Followers - unsupported"` plain text |
-
-### Expected Full Rendering
-
-| Element          | Description                             |
-| ---------------- | --------------------------------------- |
-| Card header      | `"Followers"` + count badge             |
-| Follower avatars | Row of avatar initials circles          |
-| Follow button    | Toggle button `"Follow"` / `"Unfollow"` |
-
-**CSS-only implementation notes (stub):**
-
-- Card: standard card layout — `border-radius: 4px; box-shadow: 0 1px 4px rgba(0,0,0,0.12); padding: 1rem`.
-- Unsupported message: `color: var(--secondary-text-color); font-size: 0.875rem`.
-
-**CSS-only implementation notes (full):**
-
-- Avatar row: `display: flex; flex-wrap: wrap; gap: 4px`.
-- Avatar circle: `width: 32px; height: 32px; border-radius: 50%; background: var(--avatar-bg); display: flex; align-items: center; justify-content: center; font-size: 0.75rem; font-weight: 600`.
-
-## Edge Cases & Special Logic
-
-- If the stub message `"Followers - unsupported"` is shown in production, it means this widget has not been fully implemented yet — that is expected behavior.
-- When implementing: guard against empty follower arrays — show a `"No followers yet"` state.
-- Follow/unfollow toggle must reflect the current user's follow status — fetch this as part of the initial data load.
-
-## Dependencies
-
-- MUI: `<Card>`, `<CardContent>`, `<CardHeader>`, `<Typography>` (current stub)
-- Future full implementation would add: `<Avatar>`, `<Button>`, `<Badge>`, pub-sub subscriptions
-
-## Design System Mapping
-
-**UI control type:** Social widget — follower list with follow/unfollow action.
-
-Listed design systems are examples only.
-
-| Design System      | Card                  | Avatar                   | Toggle Button             |
-| ------------------ | --------------------- | ------------------------ | ------------------------- |
-| Default (CSS only) | `<div>` with border   | CSS circle with initials | `<button>`                |
-| MUI                | `<Card>` + `<Avatar>` | `<Avatar>`               | `<Button>` variant toggle |
-| Ant Design         | `<Card>`              | `<Avatar>`               | `<Button>`                |
-| Chakra UI          | `<Card>`              | `<Avatar>`               | `<Button>`                |
-| Shadcn/ui          | `<Card>`              | Custom avatar            | `<Button>`                |
-
-When implementing in a specific design system:
-
-- The current stub only needs a card with a message — implement the full behavior once the Pega backend supports it
-- Follow/unfollow must be scoped to the current case (`caseKey` from `pConn.getCaseInfo().getKey()`)
-- Follower count badge in the card header improves scannability

package/templates/react-sdk-reference/.github/skills/widget-skills/QuickCreate.md

@@ -1,118 +0,0 @@
-# Skill: QuickCreate
-
-Quick case creation widget. Renders a set of buttons — one per available case type — allowing users to create cases directly from the widget without navigating to a separate form.
-
-> **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
-
-Provides a shortcut panel for creating new cases. Case types are sourced from the Pega environment info (or a fallback portal config for Launchpad). The list can be filtered by class name. Each button triggers case creation via `pConn.getActionsApi().createWork()`. Rendering is delegated to the `WssQuickCreate` design system extension component.
-
-## Pega Metadata
-
-- **Registration key:** `QuickCreate` (in `component-map.ts`)
-- **Category:** Widget — action / case creation
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop            | Type       | Required | Description                                                                 |
-| --------------- | ---------- | -------- | --------------------------------------------------------------------------- |
-| `heading`       | `string`   | Yes      | Widget title (e.g., `"Create"`)                                             |
-| `showCaseIcons` | `boolean`  | No       | Whether to show case type icons alongside labels. Default `false`           |
-| `classFilter`   | `any[]`    | No       | Array of class names to filter available case types. Empty array = show all |
-| `getPConnect`   | `function` | Yes      | PConnect getter                                                             |
-
-## Behavioral Contract
-
-### Case Types Resolution
-
-1. Read `PCore.getEnvironmentInfo().environmentInfoObject.pyCaseTypeList` — the primary source.
-2. If the list is empty or unavailable (e.g., Launchpad mode), fall back to the app portal config:
-   ```
-   PCore.getConfig().getApplicationName()  // or portal config equivalent
-   ```
-3. Apply `classFilter`: if `classFilter` is non-empty, retain only case types whose class name is included in the array.
-
-### Case Type Object Mapping
-
-For each case type, build:
-
-```typescript
-{
-  classname: caseType.pyClassName,
-  label: caseType.pyLabel,
-  onClick: () => pConn.getActionsApi().createWork(caseType.pyClassName, {
-    openCaseViewAfterCreate: true,
-    containerName: PCore.getConstants().APP.APP
-  }),
-  icon: showCaseIcons ? getIconURL(caseType.pyClassName) : undefined
-}
-```
-
-### Rendering Delegation
-
-Pass the mapped case type array to `WssQuickCreate` (retrieved via `getComponentFromRegistry('WssQuickCreate')`):
-
-```tsx
-const WssQuickCreate = getComponentFromRegistry('WssQuickCreate');
-return <WssQuickCreate heading={heading} caseTypes={caseTypeObjects} />;
-```
-
-This component handles all button rendering — `QuickCreate` is purely a data-preparation orchestrator.
-
-## Visual Specifications
-
-Visual rendering is owned by `WssQuickCreate` (a design system extension component). Typical layout:
-
-| Element           | Description                                       |
-| ----------------- | ------------------------------------------------- |
-| Heading           | Widget title at the top                           |
-| Case type buttons | One button per case type; icon (optional) + label |
-
-**CSS-only implementation notes (if implementing without `WssQuickCreate`):**
-
-- Container: `display: flex; flex-direction: column; gap: 0.5rem`.
-- Heading: `font-weight: 600; margin-bottom: 0.5rem`.
-- Case type button: `display: flex; align-items: center; gap: 0.5rem; padding: 8px 12px; border: 1px solid var(--border-color); border-radius: 4px; cursor: pointer; background: white`.
-- Icon: `width: 20px; height: 20px; object-fit: contain`.
-
-## Edge Cases & Special Logic
-
-- `classFilter` is an empty array by default — empty array means **no filtering** (show all case types).
-- If `pyCaseTypeList` is empty and the fallback also produces no results, render the widget with a `"No case types available"` message or hide the widget.
-- `showCaseIcons` requires a valid icon URL — `getIconURL(classname)` returns `undefined` if no icon is configured; guard against rendering a broken `<img>`.
-- `createWork` opens the case creation form in the primary container. If the user already has an unsaved case open, behavior depends on container configuration (may replace or open in a new tab).
-
-## Dependencies
-
-- `getComponentFromRegistry('WssQuickCreate')` — design system extension for case type button rendering
-- `pConn.getActionsApi().createWork()` — triggers case creation
-- `PCore.getEnvironmentInfo()` — primary source for available case types
-- `PCore.getConstants().APP.APP` — app context constant
-
-## Design System Mapping
-
-**UI control type:** Quick-action panel with one button per available case type.
-
-Listed design systems are examples only.
-
-Rendering is delegated to `WssQuickCreate` — implement that DSE component for your design system. `QuickCreate` itself has no direct UI output beyond the delegation.
-
-If implementing without `WssQuickCreate`:
-
-| Design System      | Button List                                               |
-| ------------------ | --------------------------------------------------------- |
-| Default (CSS only) | `<button>` list with optional `<img>` icon                |
-| MUI                | `<List>` + `<ListItemButton>` or `<Button>` stack         |
-| Ant Design         | `<Space direction='vertical'>` + `<Button>` per case type |
-| Chakra UI          | `<VStack>` + `<Button>` per case type                     |
-| Shadcn/ui          | `<div>` stack + `<Button variant='outline'>`              |
-
-When implementing in a specific design system:
-
-- `classFilter` empty array = show ALL case types (not zero) — this is a common gotcha
-- `createWork` must be called with the correct `containerName` constant (`APP.APP`)
-- `showCaseIcons` is optional — only fetch/render icons when this prop is `true`

package/templates/react-sdk-reference/.github/skills/widget-skills/SummaryItem.md

@@ -1,169 +0,0 @@
-# Skill: SummaryItem
-
-Individual item card for displaying an attachment, file, or link with an icon, name, metadata, and an actions menu. Also covers `SummaryList` — the container that renders multiple `SummaryItem` cards.
-
-> **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
-
-`SummaryItem` renders a single row/card for an attachment or link item. It shows a file-type icon, the item name (as a link for URLs or plain text for files), secondary metadata text, and an action menu. Used by `FileUtility` via the `SummaryList` container.
-
-`SummaryList` is a thin wrapper that maps an array of item objects to individual `SummaryItem` cards, passing down menu icon overrides for all items.
-
-## Pega Metadata
-
-- **Registration keys:**
-  - `SummaryItem` — the individual item card
-  - `SummaryList` — the container/list component
-- **Category:** Widget — display / composition
-- **Extends:** `PConnProps`
-
----
-
-## SummaryItem
-
-### Props
-
-| Prop                      | Type       | Required | Description                                                                             |
-| ------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------- |
-| `arItems$`                | `object`   | Yes      | A single item object (see Item Structure below)                                         |
-| `menuIconOverride$`       | `string`   | No       | If provided, replaces the standard actions menu with a single direct-action icon button |
-| `menuIconOverrideAction$` | `function` | No       | Callback invoked when the override icon button is clicked                               |
-| `getPConnect`             | `function` | Yes      | PConnect getter                                                                         |
-
-### Item Structure (`arItems$`)
-
-```typescript
-{
-  id: string;
-  visual: {
-    icon: string;        // Icon identifier or URL
-    progress?: number;   // Upload progress 0–100 (optional)
-  };
-  primary: {
-    type: 'FILE' | 'URL';
-    name: string;        // Display name of the item
-    icon: string;        // Icon for the primary element
-    click: () => void;   // Download (FILE) or open in new tab (URL)
-  };
-  secondary: {
-    text: string;        // Metadata text (e.g., "John Smith · 01/15/2025")
-    error?: boolean;     // If true, render text in error/red color
-  };
-  actions: Array<{
-    id: string;
-    text: string;        // Menu item label
-    icon: string;        // Menu item icon identifier
-    onClick: () => void; // Action callback
-  }>;
-}
-```
-
-### Behavioral Contract
-
-1. **Visual area:** Render `visual.icon` (file type icon). If `visual.progress` is defined and between 0–99, overlay a progress indicator.
-2. **Primary element:**
-   - `type === 'FILE'`: render `primary.name` as plain text (clicking calls `primary.click` which triggers download).
-   - `type === 'URL'`: render `primary.name` as a link button that calls `primary.click` (opens URL in new tab).
-3. **Secondary text:** Render `secondary.text` below the primary element. If `secondary.error === true`, render in error/red color.
-4. **Actions:**
-   - **Standard mode (no `menuIconOverride$`):** Render a `<MoreVertIcon>` icon button. On click, open a `<Menu>` with one `<MenuItem>` per `actions` entry.
-   - **Override mode (`menuIconOverride$` provided):** Render a single direct-action icon button using `menuIconOverride$` as the icon. On click, call `menuIconOverrideAction$()`. No menu rendered.
-
-## Visual Specifications
-
-### Item Layout
-
-```
-[File Icon]  [Name (link if URL)]
-             [Secondary metadata text]
-                                    [Actions button (⋮ or override)]
-```
-
-| Element        | Description                                   |
-| -------------- | --------------------------------------------- |
-| File icon      | Left side, fixed size (~36px square)          |
-| Name           | Bold, truncated with ellipsis if too long     |
-| Metadata       | Smaller, secondary-color text                 |
-| Actions button | Right side, `<MoreVertIcon>` or override icon |
-
-**CSS-only implementation notes:**
-
-- Row: `display: flex; align-items: center; gap: 0.75rem; padding: 8px 0`.
-- File icon: `width: 36px; height: 36px; flex-shrink: 0`.
-- Content area: `flex: 1; min-width: 0` (prevents text overflow).
-- Name: `font-size: 0.875rem; font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap`.
-- Metadata: `font-size: 0.75rem; color: var(--secondary-text-color)`.
-- Error metadata: `color: var(--error-color)`.
-- Actions button: `flex-shrink: 0; margin-left: auto`.
-- URL name: `color: var(--link-color); cursor: pointer; text-decoration: underline`.
-
-## Edge Cases & Special Logic
-
-- `visual.progress` — show a progress indicator only when `0 <= progress < 100`. When `progress === 100` (complete) or `progress === undefined`, show only the file icon.
-- `secondary.error === true` — the metadata text (e.g., upload error message) must be red, not the normal secondary color.
-- `menuIconOverride$` replaces the menu entirely — do not render `<MoreVertIcon>` when an override is provided.
-- `actions` may be empty — if empty and no override provided, do not render the actions button at all.
-
----
-
-## SummaryList
-
-### Props
-
-| Prop                      | Type       | Required | Description                                                      |
-| ------------------------- | ---------- | -------- | ---------------------------------------------------------------- |
-| `arItems$`                | `any[]`    | Yes      | Array of item objects (same shape as `SummaryItem`'s `arItems$`) |
-| `menuIconOverride$`       | `string`   | No       | Passed to every `SummaryItem`                                    |
-| `menuIconOverrideAction$` | `any`      | No       | Passed to every `SummaryItem`                                    |
-| `getPConnect`             | `function` | Yes      | PConnect getter                                                  |
-
-### Behavioral Contract
-
-```tsx
-const SummaryItemComp = getComponentFromRegistry('SummaryItem');
-
-return (
-  <div>
-    {arItems$.map((item, i) => (
-      <SummaryItemComp
-        key={item.id || i}
-        arItems$={item}
-        menuIconOverride$={menuIconOverride$}
-        menuIconOverrideAction$={menuIconOverrideAction$}
-        getPConnect={getPConnect}
-      />
-    ))}
-  </div>
-);
-```
-
-No state, no data fetching — purely a mapping wrapper.
-
-## Dependencies
-
-- **SummaryItem:** MUI `<IconButton>`, `<Menu>`, `<MenuItem>`, MUI Icons `<MoreVertIcon>`, utils helper for icon path resolution
-- **SummaryList:** `getComponentFromRegistry('SummaryItem')` — resolves the item component dynamically
-
-## Design System Mapping
-
-**UI control type:** File/link item row with icon, name, metadata, and action menu.
-
-Listed design systems are examples only.
-
-| Design System      | Row Layout                             | Action Menu                          |
-| ------------------ | -------------------------------------- | ------------------------------------ |
-| Default (CSS only) | `<div>` flexbox row                    | `<button>` + custom dropdown         |
-| MUI                | `<ListItem>` or `<Box display='flex'>` | `<IconButton>` + `<Menu>/<MenuItem>` |
-| Ant Design         | `<List.Item>`                          | `<Dropdown menu={{ items }}>`        |
-| Chakra UI          | `<HStack>`                             | `<Menu>/<MenuButton>/<MenuList>`     |
-| Shadcn/ui          | `<div>` flexbox                        | `<DropdownMenu>`                     |
-
-When implementing in a specific design system:
-
-- `menuIconOverride$` completely replaces the standard `⋮` menu — check for it before rendering the actions area
-- `type === 'URL'` must render the name as a clickable link (not plain text)
-- `secondary.error` is a boolean — apply error styling to the `secondary.text` when `true`
-- `SummaryList` is purely compositional — no logic beyond mapping items to `SummaryItem`