@pega/sdk 0.0.5 → 0.0.7

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/Operator.md

@@ -2,7 +2,7 @@
 
 Read-only display of a Pega case operator (creator or updater). Shows the operator's name and relative timestamp. On click, fetches full operator details from Pega and displays them in a popover.
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
@@ -13,14 +13,14 @@ Renders a clickable read-only field displaying a case operator's name and the re
 ## Pega Metadata
 
 - **Pega Name:** `Operator`
-- **Registration key:** `Operator` (in `component-map.ts`)
-- **Extends `PConnProps`** — but does NOT call `getPConnect()`. Props are all passed directly.
+- **Registration key:** `Operator` (in the project's component map)
+- **Extends the base component interface** — but does NOT call `getPConnect()`. All rendering data is passed directly as inputs.
 
-## Props
+## Component Inputs
 
-The component interface extends `PConnProps` but all rendering data is passed as explicit props:
+The component extends the project's base component interface but all rendering data is passed as explicit inputs. Define the input contract using the project's framework conventions.
 
-| Prop             | Type                                   | Required | Description                                                                                                                        |
+| Name             | Type                                   | Required | Description                                                                                                                        |
 | ---------------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | `label`          | `string`                               | Yes      | The field label used to identify which operator to display. Must be `'create operator'` or `'update operator'` (case-insensitive). |
 | `displayLabel`   | `any`                                  | No       | Alternative label (used if `label` doesn't match). Also compared case-insensitively.                                               |
@@ -31,72 +31,59 @@ The component interface extends `PConnProps` but all rendering data is passed as
 | `updateLabel`    | `string`                               | Yes      | Display label for the update operator field                                                                                        |
 | `updateOperator` | `{ userName: string; userId: string }` | Yes      | Updater's name and ID                                                                                                              |
 
-## Component Skeleton
-
-```typescript
-import { useState } from 'react';
-import { Utils } from '../../helpers/utils';
-import type { PConnProps } from '@pega/sdk-react';
-
-interface OperatorProps extends PConnProps {
-  label: string; displayLabel?: any;
-  createDateTime: string; createLabel: string; createOperator: { userName: string; userId: string };
-  updateDateTime: string; updateLabel: string; updateOperator: { userName: string; userId: string };
-}
-
-export default function Operator(props: OperatorProps) {
-  const { label, displayLabel, createDateTime, createLabel, createOperator,
-    updateDateTime, updateLabel, updateOperator } = props;
-  const [popoverAnchorEl, setPopoverAnchorEl] = useState(null);
-  const [popoverFields, setPopoverFields] = useState([]);
-
-  // 1. Operator selection based on label/displayLabel
-  let caseOpLabel = '---', caseOpName = '---', caseOpId = '', caseTime = '';
-  const labelLower = (label || displayLabel || '').toLowerCase();
-  if (labelLower === 'create operator') {
-    caseOpLabel = createLabel; caseOpName = createOperator.userName;
-    caseOpId = createOperator.userId; caseTime = createDateTime;
-  } else if (labelLower === 'update operator') {
-    caseOpLabel = updateLabel; caseOpName = updateOperator.userName;
-    caseOpId = updateOperator.userId; caseTime = updateDateTime;
-  }
-
-  // 2. Click handler: fetch operator details + open popover
-  const showOperatorDetails = (event) => {
-    if (!caseOpId) return;
-    PCore.getUserApi().getOperatorDetails(caseOpId).then(res => {
-      const info = res.data?.pyOperatorInfo || {};
-      const localizedVal = PCore.getLocaleUtils().getLocaleValue;
-      setPopoverFields([
-        { label: localizedVal('Position', 'Operator'), value: info.pyPosition || '---' },
-        { label: localizedVal('Organization', 'Operator'), value: info.pyOrganization || '---' },
-        { label: localizedVal('Reports to', 'Operator'), value: info.pyReportToUserName || '---' },
-        { label: localizedVal('Telephone', 'Operator'), value: info.pyTelephone || '---', href: `tel:${info.pyTelephone}` },
-        { label: localizedVal('Email address', 'Operator'), value: info.pyEmailAddress || '---', href: `mailto:${info.pyEmailAddress}` },
-      ]);
-      setPopoverAnchorEl(event.currentTarget);
-    });
-  };
-
-  // 3. Render: read-only clickable field + relative time + popover
-  return (
-    <div>
-      <ReadOnlyField label={caseOpLabel} value={caseOpName}
-        onClick={showOperatorDetails} style={{ cursor: 'pointer' }} />
-      <RelativeTime>{Utils.generateDateTime(caseTime, 'DateTime-Since')}</RelativeTime>
-      <Popover anchorEl={popoverAnchorEl} onClose={() => setPopoverAnchorEl(null)}>
-        <h6>{caseOpName}</h6>
-        {popoverFields.map(f => (
-          <Row key={f.label}>
-            <Caption>{f.label}</Caption>
-            <Value>{f.href ? <a href={f.href}>{f.value}</a> : f.value}</Value>
-          </Row>
-        ))}
-      </Popover>
-    </div>
-  );
-}
-```
+## Implementation Structure
+
+### Module Setup
+
+The component imports:
+
+- A local state mechanism for popover visibility and content
+- The project's `Utils` helper for relative date/time formatting
+- The project's base component interface (the component extends it, though `getPConnect()` is not called)
+
+The component is named `Operator` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### State
+
+Maintain two state variables:
+
+- `popoverAnchorEl` (initially `null`) — the DOM element the popover is anchored to; setting it opens the popover.
+- `popoverFields` (initially `[]`) — array of field objects to display inside the popover.
+
+### Operator Selection Logic
+
+At the top of the component logic, determine which operator to display:
+
+1. Coalesce `label` and `displayLabel` into a single string, then lowercase it.
+2. If the lowercased value equals `'create operator'`: use `createLabel`, `createOperator.userName`, `createOperator.userId`, and `createDateTime`.
+3. If the lowercased value equals `'update operator'`: use `updateLabel`, `updateOperator.userName`, `updateOperator.userId`, and `updateDateTime`.
+4. Otherwise: set label and name to `'---'`, id and time to empty strings.
+
+Store these as local variables: `caseOpLabel`, `caseOpName`, `caseOpId`, `caseTime`.
+
+### Click Handler (`showOperatorDetails`)
+
+Define an event handler that:
+
+1. Early-returns if `caseOpId` is empty (no operator to fetch).
+2. Calls `PCore.getUserApi().getOperatorDetails(caseOpId)` — an async API that returns operator profile data.
+3. Uses `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` to localize field label strings.
+4. On resolution, builds a `popoverFields` array with these entries (each with `label`, `value`, and optional `href`):
+   - Position (`pyPosition`) — no href
+   - Organization (`pyOrganization`) — no href
+   - Reports to (`pyReportToUserName`) — no href
+   - Telephone (`pyTelephone`) — `href: 'tel:{value}'`
+   - Email address (`pyEmailAddress`) — `href: 'mailto:{value}'`
+   - All values fall back to `'---'` if the property is missing/falsy.
+5. Sets `popoverAnchorEl` to `event.currentTarget` (opens the popover).
+
+### Render Tree
+
+1. **Read-only text display** — no underline/border, `readOnly: true`, `cursor: pointer`. Shows `caseOpName` as value and `caseOpLabel` as the field label. Wires click handler to `showOperatorDetails`.
+2. **Relative time** — below the text display, render the output of `Utils.generateDateTime(caseTime, 'DateTime-Since')` as helper/caption text.
+3. **Popover** — anchored to the clicked element, closed by clearing the anchor reference:
+   - Header: operator name (`caseOpName`) in heading-6 text (≈1.25rem, weight 500).
+   - Body: iterate `popoverFields`, rendering each as a row with a caption-style label (6 columns) and a subtitle-style value (6 columns). For fields with `href`, wrap the value in an `<a>` tag with the href.
 
 ## Behavioral Contract
 
@@ -118,18 +105,18 @@ Determine which operator to display based on `label.toLowerCase()` or `displayLa
 
 ### 2. Main Display
 
-Render a read-only TextField (standard variant, no underline, pointer cursor) with:
+Render a read-only text display element (no underline/border, pointer cursor) with:
 
 - `defaultValue={caseOpName}`
 - `label={caseOpLabel}`
-- `onClick={showOperatorDetails}`
-- `readOnly: true`, `disableUnderline: true`, `cursor: 'pointer'`
+- Click handler wired to `showOperatorDetails`
+- `readOnly: true`, no underline/border, `cursor: 'pointer'`
 
-Below the TextField, render the relative time: `Utils.generateDateTime(caseTime, 'DateTime-Since')`.
+Below the text display, render the relative time: `Utils.generateDateTime(caseTime, 'DateTime-Since')`.
 
 ### 3. Popover on Click (`showOperatorDetails`)
 
-When the TextField is clicked:
+When the text display is clicked:
 
 1. Call `PCore.getUserApi().getOperatorDetails(caseOpId)` — returns a Promise.
 2. Use `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` to localize field labels.
@@ -150,30 +137,30 @@ The popover renders when `popoverAnchorEl` is set:
 - Anchor origin: `{ vertical: 'bottom', horizontal: 'center' }`
 - Transform origin: `{ vertical: 'top', horizontal: 'center' }`
 - Max width: `45ch`
-- Content: A `Grid container` with:
-  - `Typography h6` showing `caseOpName` at full width.
-  - One row per field: 6-col `Typography caption` (label) + 6-col `Typography subtitle2` (value).
+- Content: A grid layout with:
+  - Heading-6 text (≈1.25rem, weight 500) showing `caseOpName` at full width.
+  - One row per field: 6-col caption text (label) + 6-col subtitle text (value).
 
-Closing the popover sets `popoverAnchorEl` to `null`.
+Closing the popover clears the anchor reference.
 
 ## Visual Specifications
 
-Derived from `Operator.tsx` makeStyles:
+Derived from the component's companion styles:
 
 ### Root Container
 
-| Property | Value                      |
-| -------- | -------------------------- |
-| Padding  | `theme.spacing(1)` (≈ 8px) |
-| Margin   | `theme.spacing(1)`         |
+| Property | Value                  |
+| -------- | ---------------------- |
+| Padding  | 1 spacing unit (≈ 8px) |
+| Margin   | 1 spacing unit         |
 
 ### Popover Container
 
-| Property  | Value              |
-| --------- | ------------------ |
-| Padding   | `theme.spacing(1)` |
-| Margin    | `theme.spacing(1)` |
-| Max width | 45ch               |
+| Property  | Value          |
+| --------- | -------------- |
+| Padding   | 1 spacing unit |
+| Margin    | 1 spacing unit |
+| Max width | 45ch           |
 
 **CSS-only implementation notes:**
 
@@ -195,7 +182,7 @@ Derived from `Operator.tsx` makeStyles:
 
 ## Dependencies
 
-- `Utils` from `../../helpers/utils` — `Utils.generateDateTime` for relative time display
+- The project's `Utils` helper — `Utils.generateDateTime` for relative time display
 - `PCore.getUserApi().getOperatorDetails(userId)` — global Pega runtime API for operator details
 - `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` — for localized field labels in the popover
 
@@ -203,20 +190,10 @@ Derived from `Operator.tsx` makeStyles:
 
 **UI control type:** Clickable read-only field with async popover detail panel.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                           |
-| ------------------ | --------------------------------------------------------------- |
-| Default (CSS only) | `<div>` with click handler, custom CSS popover/tooltip panel    |
-| MUI                | Read-only `<TextField>` + `<Popover>` with `<Grid>` detail rows |
-| Ant Design         | `<Input readOnly>` + `<Popover>` with `<Descriptions>`          |
-| Chakra UI          | `<Input isReadOnly>` + `<Popover>` with custom content          |
-| Shadcn/ui          | `<Input readOnly>` + `<Popover>` + `<PopoverContent>`           |
-
 When implementing in a specific design system, map the following:
 
-- `onClick` on read-only input → trigger async fetch + open popover
-- `PCore.getUserApi().getOperatorDetails()` → call this before showing the popover
-- Popover anchor → position relative to the clicked element
-- `Utils.generateDateTime(caseTime, 'DateTime-Since')` → relative time display (e.g., "2 hours ago")
-- Telephone/email in popover → clickable `<a href='tel:...'>` and `<a href='mailto:...'>` links
+- **Read-only clickable field** → use the DS's read-only input/text display with pointer cursor and click handler
+- **Popover/tooltip** → use the DS's popover component anchored to the clicked element, with close-on-outside-click behavior
+- **Popover content** → a grid layout with heading (operator name) and label/value rows
+- **Relative time** → render `Utils.generateDateTime(caseTime, 'DateTime-Since')` as secondary/muted caption text below the operator name
+- **Telephone/email** → clickable `<a href='tel:...'>` and `<a href='mailto:...'>` links in the popover

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/Pulse.md

@@ -2,7 +2,7 @@
 
 Placeholder activity feed / comments stream card. Currently a stub implementation that renders a card titled "Pulse".
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
@@ -13,41 +13,41 @@ Renders a card container intended to display an activity feed or comments stream
 ## Pega Metadata
 
 - **Pega Name:** `Pulse`
-- **Registration key:** `Pulse` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives children via `PropsWithChildren`
+- **Registration key:** `Pulse` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives children via the framework's content projection mechanism
 
-## Props
+## Component Inputs
 
-| Prop       | Type        | Required | Description                                                               |
-| ---------- | ----------- | -------- | ------------------------------------------------------------------------- |
-| `children` | `ReactNode` | No       | Child components (activity stream content) — currently unused in the stub |
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
 
-## Component Skeleton
+| Name       | Type               | Required | Description                                                               |
+| ---------- | ------------------ | -------- | ------------------------------------------------------------------------- |
+| `children` | renderable content | No       | Child components (activity stream content) — currently unused in the stub |
+
+## Implementation Structure
 
 Stub implementation — placeholder only.
 
-```typescript
-import type { PropsWithChildren } from 'react';
+### Module Setup
+
+The component accepts children via the framework's content projection mechanism. It does NOT import any Pega SDK modules.
+
+The component is named `Pulse` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
 
-export default function Pulse(props: PropsWithChildren<{}>) {
-  // Stub: renders a card with left accent border and placeholder content
-  return (
-    <Card style={{ marginTop: '8px', marginBottom: '8px', borderLeft: '6px solid var(--app-primary-light-color)' }}>
-      <CardHeader><h6>Pulse</h6></CardHeader>
-      <CardContent>Pulse</CardContent>
-    </Card>
-  );
-}
-```
+### Component Logic
 
-> A production implementation would render `props.children` (the activity stream) inside the card body.
+The component receives `children` as input (though the current stub does not render them), then:
 
-> **Note:** The current reference implementation ignores `children` and renders placeholder content. A full implementation would render `children` inside the card body.
+1. **Render a Card container** — a card-style element with a distinct 6px left border accent using the primary light color from the design system's palette (or CSS variable `--app-primary-light-color`). Apply top and bottom margin of 1 spacing unit (≈ 8px).
+2. **Render a CardHeader** — containing a heading (heading-6 text, ≈1.25rem, weight 500) with the text `"Pulse"`.
+3. **Render CardContent** — containing placeholder text `"Pulse"`.
+
+> **Note:** The current reference implementation ignores `children` and renders placeholder content. A production implementation would render the children (the activity stream) inside the card body.
 
 ## Behavioral Contract
 
 1. Render a `Card` (or equivalent container) with a distinct left border accent.
-2. Render a card header with the title text `"Pulse"` using a heading style (e.g., `h6`).
+2. Render a card header with the title text `"Pulse"` using a heading style (heading-6, ≈1.25rem, weight 500).
 3. Render card content body with placeholder text `"Pulse"`.
 4. The left border accent uses the **primary light** color from the design system's theme.
 5. The card has top and bottom margin (1 spacing unit each).
@@ -56,16 +56,16 @@ export default function Pulse(props: PropsWithChildren<{}>) {
 
 ## Visual Specifications
 
-Derived from `Pulse.tsx` makeStyles:
+Derived from the component's companion styles:
 
 ### Card Container
 
-| Property          | Value                                                                    |
-| ----------------- | ------------------------------------------------------------------------ |
-| Margin top        | `theme.spacing(1)` (≈ 8px in MUI default)                                |
-| Margin bottom     | `theme.spacing(1)` (≈ 8px)                                               |
-| Border left       | `6px solid`                                                              |
-| Border left color | `theme.palette.primary.light` (light variant of the primary brand color) |
+| Property          | Value                                                |
+| ----------------- | ---------------------------------------------------- |
+| Margin top        | 1 spacing unit (≈ 8px)                               |
+| Margin bottom     | 1 spacing unit (≈ 8px)                               |
+| Border left       | `6px solid`                                          |
+| Border left color | Primary light color from the design system's palette |
 
 **CSS-only implementation notes:**
 
@@ -76,8 +76,8 @@ Derived from `Pulse.tsx` makeStyles:
 
 ## Edge Cases & Special Logic
 
-- The `children` prop is received but not currently rendered — it is intentional in the stub.
-- The component renders unconditionally (no conditional logic based on props).
+- The `children` input is received but not currently rendered — it is intentional in the stub.
+- The component renders unconditionally (no conditional logic based on inputs).
 
 ## Dependencies
 
@@ -88,18 +88,10 @@ Derived from `Pulse.tsx` makeStyles:
 
 **UI control type:** Card with left accent border and header/body sections.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                                   |
-| ------------------ | --------------------------------------------------------------------------------------- |
-| Default (CSS only) | `<div>` with `border-left: 6px solid` + inner header/body divs                          |
-| MUI                | `<Card><CardHeader title={<Typography variant='h6'>Pulse</Typography>} /><CardContent>` |
-| Ant Design         | `<Card title='Pulse'>` with left border via `style` prop                                |
-| Chakra UI          | `<Card>` with `borderLeft='6px solid' borderColor='blue.300'`                           |
-| Shadcn/ui          | `<Card><CardHeader><CardTitle>`                                                         |
-
 When implementing in a specific design system, map the following:
 
-- Left border accent → `borderLeft` / `border-left` on the card root
-- Left border color → primary light color from the design system's palette
+- **Card container** → use the DS's card component (or a bordered container element)
+- **Left border accent** → apply `border-left: 6px solid` with the DS's primary-light color
+- **Card header** → use the DS's card header/title slot with heading-6 text
+- **Card body** → use the DS's card content/body slot
 - Card header title typography → design system's heading variant (h6 or equivalent)