@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/{.github → .ai-common}/skills/widget-skills/FileUtility.md

@@ -2,7 +2,7 @@
 
 File and URL management utility widget. Displays case attachments and links, supports upload/download/delete, and provides modals for adding new files or URLs. Also covers `ActionButtonsForFileUtil` sub-component.
 
-> **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, input contract, data-fetching patterns, and registration conventions common to ALL widget components.
 
 ---
 
@@ -12,30 +12,54 @@ The primary attachments management panel in the case utilities column. Shows up
 
 ## Pega Metadata
 
-- **Registration key:** `FileUtility` (in `component-map.ts`)
+- **Registration key:** `FileUtility` (in the project's component map)
 - **Category:** Widget — file management
-- **Extends:** `PConnProps`
+- **Extends:** The project's base component interface
 
-## Props
+## Inputs
 
 | Prop          | Type       | Required | Description                                                                       |
 | ------------- | ---------- | -------- | --------------------------------------------------------------------------------- |
 | `caseId`      | `string`   | No       | Optional case ID override. If absent, resolved from `pConn.getCaseInfo().getID()` |
 | `getPConnect` | `function` | Yes      | PConnect getter                                                                   |
 
+## Implementation Structure
+
+This is the largest widget (~500 lines). Key structural outline:
+
+**Module Setup:** The component depends on lifecycle effects and local state management, a debounce utility, a file-download utility, the project's SDK utility helpers, the project's attachment-validation helpers, and the project's component registry (to resolve `SummaryList` and `ActionButtonsForFileUtil`). Define the input contract as an extension of the project's base component interface.
+
+**Main Component Logic** — steps in order:
+
+1. Resolve `SummaryList` and `ActionButtonsForFileUtil` from the project's component registry. Receive `getPConnect` and `caseId` from inputs; call `getPConnect()` into `thePConn`; resolve `caseID` from `caseId ?? thePConn.getValue(PCore.getConstants().CASE_INFO.CASE_INFO_ID, '')`.
+2. Declare state: `list` (an object with `data` array and `count`, default `{ data: [], count: 0 }`) for the top-3 display; `fileData` (an object tracking the add-file modal's `showfileModal`, `fileList`, `attachedFiles`, and related fields); `linkData` (an object tracking the add-link modal's `showLinkModal`, `linksList`, `attachedLinks`, and related fields); and `link` (an object with `title`, `url`, and `disable`, default `{ title: '', url: '', disable: true }`).
+3. Define `getAttachments`: fetches case attachments and builds `SummaryItem`-compatible objects from them.
+4. Define `debouncedGetAttachments` as `debounce(getAttachments, 1000)`.
+5. In a lifecycle effect, subscribe to the messaging service for attachment-change events so the list stays fresh.
+6. Define `downloadAttachedFile` and `deleteAttachedFile` handlers.
+7. Define `onAttachFiles`: uploads the selected file(s) and links them to the case.
+8. Define `onAttachLinks`: links the given URL(s) to the case with the URL category.
+9. **Render**: a `Card` containing a header, a `SummaryList` showing the top 3 items, and a "View all" button; an Add File modal (file input + `SummaryList` + `ActionButtonsForFileUtil`); an Add Link modal (title + url fields + `ActionButtonsForFileUtil`); and a View All modal (the full `SummaryList`).
+
+> **Key patterns:** Debounced refresh (1000ms) on messaging subscription, `linkAttachmentsToCase` after upload, `ActionButtonsForFileUtil` for modal button rows, `SummaryList` for item display.
+
 ## Behavioral Contract
 
 ### Attachment Fetch
 
-On mount and on attachment change events:
+On mount and on attachment change events, resolve `caseID` from `caseId ?? thePConn.getValue(PCore.getConstants().CASE_INFO.CASE_INFO_ID, '')` — do NOT use `pConn.getCaseInfo().getID()`, since it may return the wrong format — then call `PCore.getAttachmentUtils().getCaseAttachments(caseID, context)`.
+
+Returns array of attachment/link objects. Store in `attachments` state. Guard: only fetch if `caseID` is non-empty.
+
+### Pub/Sub Subscription
 
-```
-PCore.getAttachmentUtils().getCaseAttachments(caseKey, context)
-```
+Subscribe to the case attachments event for auto-refresh: resolve `eventName` from `(PCore.getEvents().getCaseEvent() as any).CASE_ATTACHMENTS_UPDATED_FROM_CASEVIEW`, then call `PCore.getPubSubUtils().subscribe(eventName, refresh, 'FileUtility')`. On cleanup, call `PCore.getPubSubUtils().unsubscribe(eventName, 'FileUtility')`.
 
-Returns array of attachment/link objects. Store in `attachments` state.
+This ensures attachments refresh when CaseView publishes the update event.
 
-Debounced auto-refresh: on `CASE_ATTACHMENTS_UPDATED` pub-sub event, wait 1000ms (debounced) then re-fetch. This prevents rapid re-fetches when multiple files are uploaded simultaneously.
+### Menu Actions
+
+"Add files" and "Add links" should be in a **dropdown menu** (overflow/three-dot icon or text dropdown), NOT as plain buttons. The reference uses a `<Menu>` + `<MenuItem>` pattern.
 
 ### Main View — Top 3 Display
 
@@ -43,42 +67,33 @@ Show only the first 3 items from `attachments`. If `attachments.length > 3`, sho
 
 ### SummaryList Integration
 
-Map each attachment/link to a `SummaryItem`-compatible object:
-
-```typescript
-{
-  id: attachment.ID,
-  visual: { icon: getFileIcon(attachment.mimeType) },
-  primary: {
-    type: attachment.category === 'FILE' ? 'FILE' : 'URL',
-    name: attachment.name,
-    click: () => handleDownloadOrOpen(attachment)
-  },
-  secondary: { text: attachment.createdBy + ' · ' + formatDate(attachment.createTime) }
-  actions: [
-    { id: 'delete', text: 'Delete', icon: 'trash', onClick: () => handleDelete(attachment.ID) }
-  ]
-}
-```
-
-Pass to `<SummaryList arItems$={summaryItems} />`.
+Map each attachment/link to a `SummaryItem`-compatible object with: `id` from `attachment.ID`; `visual.icon` from `getFileIcon(attachment.mimeType)`; a `primary` object with `type` set to `'FILE'` or `'URL'` based on `attachment.category`, `name` from `attachment.name`, and a `click` handler that calls `handleDownloadOrOpen(attachment)`; a `secondary.text` combining `attachment.createdBy` and the formatted `attachment.createTime`; and an `actions` array with a single delete entry (`id: 'delete'`, label "Delete", trash icon, calling `handleDelete(attachment.ID)` on click).
+
+Pass the resulting array to `<SummaryList arItems$={summaryItems} />`.
 
 ### File Upload
 
-1. User clicks "Add file" from the `<Menu>`.
-2. Opens an add-file modal (dialog).
-3. User selects a file via `<input type='file'>`.
-4. On confirm: call `PCore.getAttachmentUtils().uploadAttachment(file, onProgress, onError, context)`.
-5. On success: call `PCore.getAttachmentUtils().linkAttachmentsToCase(caseKey, [newAttachment], context)`.
-6. Refresh attachment list.
+1. User clicks "Add files" from the overflow menu (three-dot icon).
+2. Opens an add-file modal (DS Modal/Dialog component with `primaryButtonText="Attach"` and `secondaryButtonText="Cancel"`).
+3. User selects a file via the DS file uploader component — do NOT use a bare unstyled file input. Use the DS's styled file upload component for visual consistency. Show the selected file name below the button.
+4. "Attach" button is disabled until a file is selected.
+5. On confirm: call `PCore.getAttachmentUtils().uploadAttachment(file, onProgress, onError, context)`.
+6. On success: call `PCore.getAttachmentUtils().linkAttachmentsToCase(caseKey, [newAttachment], 'FILE', context)`.
+7. Close modal, clear file state, refresh attachment list.
+
+> ⚠️ Do NOT use a bare `<input type="file">` — it renders as an unstyled browser-native button. Always use the design system's file uploader component for visual consistency.
 
 ### URL Attachment
 
-1. User clicks "Add link" from the `<Menu>`.
-2. Opens add-link modal with two fields: `Title` (required) and `URL` (required).
-3. The "Attach" button is enabled only when both `title` and `url` are non-empty.
-4. On confirm: call `PCore.getAttachmentUtils().linkAttachmentsToCase(caseKey, [{ name: title, url, category: 'URL' }], context)`.
-5. Refresh attachment list.
+1. User clicks "Add links" from the overflow menu.
+2. Opens add-link modal with two DS text input fields: `Title` (required) and `URL` (required).
+3. "Attach" button is disabled until both `title` and `url` are non-empty.
+4. On confirm: call `PCore.getAttachmentUtils().linkAttachmentsToCase(caseKey, [{ name: title, url, category: 'URL' }], 'URL', context)`.
+5. Close modal, clear fields, refresh attachment list.
+
+### Menu Actions
+
+"Add files" and "Add links" MUST be in a **dropdown/overflow menu** (three-dot icon), NOT as plain text buttons. Use the DS's overflow menu or dropdown component.
 
 ### Download / Open
 
@@ -145,7 +160,7 @@ Render a `<MoreVertIcon>` `<IconButton>` that opens a `<Menu>` with:
 
 A simple button row component used inside the FileUtility modals to render Cancel + primary action buttons.
 
-### Props
+### Inputs
 
 | Prop                 | Type       | Required | Description                                                  |
 | -------------------- | ---------- | -------- | ------------------------------------------------------------ |
@@ -157,10 +172,7 @@ A simple button row component used inside the FileUtility modals to render Cance
 
 ### Layout
 
-```
-[Secondary buttons (left)]   [Primary buttons (right)]
-      Cancel                        Attach
-```
+The secondary (Cancel) buttons render on the left and the primary (Attach) buttons render on the right, in a single row.
 
 - Secondary buttons: outlined/text style.
 - Primary buttons: contained/filled style with theme primary color.
@@ -179,28 +191,22 @@ A simple button row component used inside the FileUtility modals to render Cance
 - `PCore.getAttachmentUtils()` — getCaseAttachments, uploadAttachment, downloadAttachment, deleteAttachment, linkAttachmentsToCase
 - `PCore.getMessagingServiceManager()` — subscribe to attachment change events
 - `PCore.getConstants()` — case info ID, summary refresh timing
-- `getComponentFromRegistry('SummaryList')` — renders the attachment item list
-- `getComponentFromRegistry('ActionButtonsForFileUtil')` — renders modal action buttons
-- `downloadjs` — browser file download trigger
-- MUI: `<Card>`, `<CardHeader>`, `<CardContent>`, `<IconButton>`, `<Menu>`, `<MenuItem>`, `<Button>`, `<TextField>`, `<Dialog>`, `<CircularProgress>`
-- MUI Icons: `<MoreVertIcon>`
+- The project's component registry, resolving `SummaryList` — renders the attachment item list.
+- The project's component registry, resolving `ActionButtonsForFileUtil` — renders modal action buttons.
+- A file-download utility — browser file download trigger.
+- The DS's card, icon button, menu, button, text input, modal/dialog, and progress indicator components.
 
 ## Design System Mapping
 
 **UI control type:** File management widget — attachment list with upload/download/delete and add modals.
 
-Listed design systems are examples only.
-
-| Design System      | Card         | Action Menu                          | Modal      | Progress                                   |
-| ------------------ | ------------ | ------------------------------------ | ---------- | ------------------------------------------ |
-| Default (CSS only) | `<div>` card | `<button>` + custom dropdown         | `<dialog>` | CSS progress bar                           |
-| MUI                | `<Card>`     | `<IconButton>` + `<Menu>/<MenuItem>` | `<Dialog>` | `<CircularProgress>` or `<LinearProgress>` |
-| Ant Design         | `<Card>`     | `<Dropdown menu={{ items }}>`        | `<Modal>`  | `<Progress>`                               |
-| Chakra UI          | `<Card>`     | `<Menu>/<MenuButton>/<MenuList>`     | `<Modal>`  | `<Progress>`                               |
-| Shadcn/ui          | `<Card>`     | `<DropdownMenu>`                     | `<Dialog>` | Custom progress bar                        |
-
-When implementing in a specific design system:
+When implementing in a specific design system, map the following:
 
-- Debounced refresh (1000ms) after pub-sub attachment events is required — prevents excessive API calls
+- **Card** → use the DS's card component for the main panel
+- **Action menu** → use the DS's overflow/dropdown menu (three-dot icon button)
+- **Modal/dialog** → use the DS's modal or dialog for add-file, add-link, and view-all overlays
+- **Progress indicator** → use the DS's progress bar or spinner for upload progress
+- **File upload** → use the DS's styled file uploader component (not a bare file input)
+- Debounced refresh (1000ms) after pub-sub attachment events is required
 - `linkAttachmentsToCase` must be called after upload — uploading alone does not attach to the case
 - `ActionButtonsForFileUtil` receives button definition arrays — render them generically from `arMainButtons`/`arSecondaryButtons`

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/widget-skills/Followers.md

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, input contract, data-fetching patterns, and registration conventions common to ALL widget components.
 
 ---
 
@@ -12,17 +12,29 @@ Intended to display the list of operators following a case, allowing users to fo
 
 ## Pega Metadata
 
-- **Registration key:** `Followers` (in `component-map.ts`)
+- **Registration key:** `Followers` (in the project's component map)
 - **Category:** Widget — social / collaboration
-- **Extends:** `PConnProps`
+- **Extends:** The project's base component interface
 
-## Props
+## Inputs
 
-| Prop          | Type       | Required | Description     |
+| Name          | Type       | Required | Description     |
 | ------------- | ---------- | -------- | --------------- |
 | `getPConnect` | `function` | Yes      | PConnect getter |
 
-No additional custom props in the current stub implementation. A full implementation would likely include:
+## Implementation Structure
+
+This is a stub implementation.
+
+**Module Setup:** Define the input contract as an extension of the project's base component interface, accepting children via the framework's content projection mechanism.
+
+**Main Component Logic** — steps in order:
+
+1. Render a `Card` containing a `CardHeader` with the heading text "Followers - " followed by the word "unsupported" in emphasis/italic styling, and a `CardContent` block with the plain text "Followers content".
+
+> A production implementation would fetch from `D_pyCaseFollowers` and provide follow/unfollow actions.
+
+No additional custom inputs in the current stub implementation. A full implementation would likely include:
 
 - `datasource` — data page name for follower list
 - `headerText` — widget title (e.g., `"Followers"`)
@@ -79,25 +91,18 @@ No additional custom props in the current stub implementation. A full implementa
 
 ## Dependencies
 
-- MUI: `<Card>`, `<CardContent>`, `<CardHeader>`, `<Typography>` (current stub)
-- Future full implementation would add: `<Avatar>`, `<Button>`, `<Badge>`, pub-sub subscriptions
+- The DS's card and text components (current stub).
+- Future full implementation would add: avatar, button, badge components, and 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:
+When implementing in a specific design system, map the following:
 
+- **Card** → use the DS's card component for the widget container
+- **Avatar** → use the DS's avatar/initials component for follower display
+- **Follow/unfollow toggle** → use the DS's button component with toggle state
 - 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/{.claude → .ai-common}/skills/widget-skills/QuickCreate.md

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, input contract, data-fetching patterns, and registration conventions common to ALL widget components.
 
 ---
 
@@ -12,11 +12,11 @@ Provides a shortcut panel for creating new cases. Case types are sourced from th
 
 ## Pega Metadata
 
-- **Registration key:** `QuickCreate` (in `component-map.ts`)
+- **Registration key:** `QuickCreate` (in the project's component map)
 - **Category:** Widget — action / case creation
-- **Extends:** `PConnProps`
+- **Extends:** The project's base component interface
 
-## Props
+## Inputs
 
 | Prop            | Type       | Required | Description                                                                 |
 | --------------- | ---------- | -------- | --------------------------------------------------------------------------- |
@@ -25,41 +25,32 @@ Provides a shortcut panel for creating new cases. Case types are sourced from th
 | `classFilter`   | `any[]`    | No       | Array of class names to filter available case types. Empty array = show all |
 | `getPConnect`   | `function` | Yes      | PConnect getter                                                             |
 
+## Implementation Structure
+
+**Module Setup:** The component depends on lifecycle effects, local state management, the project's SDK utility helpers, and the project's component registry (to resolve `WssQuickCreate`). Define the input contract as an extension of the project's base component interface with `heading`, `showCaseIcons`, and `classFilter` fields.
+
+**Main Component Logic** — steps in order:
+
+1. Resolve `WssQuickCreate` from the project's component registry. Receive `getPConnect`, `heading`, `showCaseIcons`, and `classFilter` from inputs; call `getPConnect()` into `pConn`. Declare `quickCreateCases` local state (default `[]`).
+2. In a lifecycle effect that runs once on initialization: read `PCore.getEnvironmentInfo()` into `envInfo`; when `envInfo?.environmentInfoObject?.pyCaseTypeList` is present, map each case type entry to `{ classname: ct.pyWorkTypeImplementationClassName, label: ct.pyWorkTypeName, onClick: () => pConn.getActionsApi().createWork(ct.pyWorkTypeImplementationClassName, {}), ...(showCaseIcons and { icon: Utils.getImageSrc(ct.pxIcon, Utils.getSDKStaticConentUrl()) } when showCaseIcons is true) }` into `defaultCases`; otherwise (Launchpad mode), fall back to reading case types from the store/portal config.
+3. Apply `classFilter`: when it has entries, filter `defaultCases` down to only those whose `classname` is included in `classFilter`; otherwise use `defaultCases` unfiltered (empty filter array means show all). Store the result via `setCases`.
+4. Delegate rendering entirely to the `WssQuickCreate` design system extension component, passing `heading` and the resolved `quickCreateCases` as its `actions` prop.
+
 ## 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
-   ```
+2. If the list is empty or unavailable (e.g., Launchpad mode), fall back to the app portal config equivalent of `PCore.getConfig().getApplicationName()`.
 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
-}
-```
+For each case type, build an object with: `classname` from `caseType.pyClassName`; `label` from `caseType.pyLabel`; an `onClick` handler that calls `pConn.getActionsApi().createWork(caseType.pyClassName, { openCaseViewAfterCreate: true, containerName: PCore.getConstants().APP.APP })`; and, when `showCaseIcons` is true, an `icon` resolved via `getIconURL(caseType.pyClassName)` (otherwise `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} />;
-```
+Pass the mapped case type array to `WssQuickCreate` (resolved from the project's component registry), passing `heading` and the resolved case type objects as its `actions` input.
 
 This component handles all button rendering — `QuickCreate` is purely a data-preparation orchestrator.
 
@@ -88,31 +79,23 @@ Visual rendering is owned by `WssQuickCreate` (a design system extension compone
 
 ## 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
+- The project's component registry, resolving `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`:
+When implementing in a specific design system without `WssQuickCreate`, map the following:
 
-| 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'>`              |
+- **Button list** → use the DS's button or list-item-button component, one per case type
+- **Icon** → render the case type icon when `showCaseIcons` is true
+- **Click handler** → wire to `pConn.getActionsApi().createWork(classname, {})`
 
-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`).
 
-- `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/{.claude → .ai-common}/skills/widget-skills/SummaryItem.md

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`widget-components.md`](../widget-components.md) — covers architecture, input contract, data-fetching patterns, and registration conventions common to ALL widget components.
 
 ---
 
@@ -18,13 +18,34 @@ Individual item card for displaying an attachment, file, or link with an icon, n
   - `SummaryItem` — the individual item card
   - `SummaryList` — the container/list component
 - **Category:** Widget — display / composition
-- **Extends:** `PConnProps`
+- **Extends:** The project's base component interface
 
 ---
 
+## Implementation Structure
+
+### SummaryItem
+
+**Module Setup:** The component depends on local state management and the project's SDK utility helpers for icon path resolution. Define the input contract as an extension of the project's base component interface with `menuIconOverride$`, `menuIconOverrideAction$`, and `arItems$` fields. Import a companion stylesheet.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `menuIconOverride$` (as a reassignable variable) from inputs; read the single item into `item` from the `arItems$` input. Resolve `imagePath` via `Utils.getIconPath(Utils.getSDKStaticConentUrl())` and build `srcImg` by concatenating `imagePath`, `item.visual.icon`, and `.svg`. Declare `anchorEl` state (default `null`) for the actions menu.
+2. When `menuIconOverride$` is provided, resolve it to a full image source via `Utils.getImageSrc(menuIconOverride$, Utils.getSDKStaticConentUrl())`.
+3. **Render** a `psdk-utility-card` container with three sections: an icon block showing `srcImg`; a main content block showing the primary element (plain text when `item.primary.type !== 'URL'`, or a link-styled button element when it is a URL, both displaying `item.primary.name`) followed by the secondary metadata text (`item.secondary.text`, styled red when `item.secondary.error` is true); and an actions block that either renders a single override icon button (calling the `menuIconOverrideAction$` callback with the item on click, shown when `menuIconOverride$` is set) or an overflow menu icon button that opens a dropdown menu listing one menu item per entry in `item.actions` (shown when no override is set).
+
+### SummaryList
+
+**Module Setup:** The component depends on the project's component registry (to resolve `SummaryItem`).
+
+**Main Component Logic** — steps in order:
+
+1. Resolve `SummaryItem` from the project's component registry. Receive `arItems$`, `menuIconOverride$` (default `''`), and `menuIconOverrideAction$` from inputs.
+2. Render a wrapping `div` containing one `SummaryItem` per entry in `arItems$`, keyed by `file.id`, passing that entry as `arItems$`, plus `menuIconOverride$` and `menuIconOverrideAction$`.
+
 ## SummaryItem
 
-### Props
+### Inputs
 
 | Prop                      | Type       | Required | Description                                                                             |
 | ------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------- |
@@ -35,31 +56,7 @@ Individual item card for displaying an attachment, file, or link with an icon, n
 
 ### 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
-  }>;
-}
-```
+Each item object has: `id` (string); a `visual` object with an `icon` (string identifier or URL) and an optional `progress` (number, upload progress 0–100); a `primary` object with `type` (`'FILE'` or `'URL'`), `name` (display name), `icon` (icon for the primary element), and `click` (a callback that downloads the file or opens the URL in a new tab); a `secondary` object with `text` (metadata, e.g. "John Smith · 01/15/2025") and an optional `error` boolean (renders the text in error/red color when true); and an `actions` array of `{ id, text, icon, onClick }` entries describing the menu items.
 
 ### Behavioral Contract
 
@@ -76,11 +73,7 @@ Individual item card for displaying an attachment, file, or link with an icon, n
 
 ### Item Layout
 
-```
-[File Icon]  [Name (link if URL)]
-             [Secondary metadata text]
-                                    [Actions button (⋮ or override)]
-```
+The file icon sits on the left, followed by the name (rendered as a link when the item is a URL) with the secondary metadata text below it, and the actions button (the overflow `⋮` icon or the override icon) anchored to the far right.
 
 | Element        | Description                                   |
 | -------------- | --------------------------------------------- |
@@ -111,7 +104,7 @@ Individual item card for displaying an attachment, file, or link with an icon, n
 
 ## SummaryList
 
-### Props
+### Inputs
 
 | Prop                      | Type       | Required | Description                                                      |
 | ------------------------- | ---------- | -------- | ---------------------------------------------------------------- |
@@ -122,44 +115,25 @@ Individual item card for displaying an attachment, file, or link with an icon, n
 
 ### 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>
-);
-```
+Resolve `SummaryItem` from the project's component registry. Render a wrapping container with one `SummaryItem` instance per entry in `arItems$` (keyed by `item.id` or its index), passing that entry as `arItems$`, plus `menuIconOverride$`, `menuIconOverrideAction$`, and `getPConnect`.
 
 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
+- **SummaryItem:** The DS's icon button and menu/dropdown components, the project's SDK utility helpers for icon path resolution.
+- **SummaryList:** The project's component registry, resolving `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.
+When implementing in a specific design system, map the following:
 
-| 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>`                     |
+- **Item row** → use the DS's list-item or flex-row container
+- **Actions menu** → use the DS's overflow/dropdown menu with an icon button trigger
+- **Override icon button** → render a single icon button with the override image when `menuIconOverride$` is set
+- **URL item** → render as a link-styled button element
 
 When implementing in a specific design system: