@pega/sdk 0.0.4 → 0.0.5

package/templates/react-sdk-reference/{.github → .ai-common}/skills/design-system-extension-skills/FieldGroup.md

@@ -31,6 +31,50 @@ Children are rendered inside a full-width inner container.
 | `collapsible`  | `boolean`   | No       | If `true`, the header acts as a collapse/expand toggle. Default `false` |
 | `instructions` | `string`    | No       | HTML string of instruction text shown between header and fields         |
 
+## Component Skeleton
+
+```typescript
+import { type PropsWithChildren, useState } from 'react';
+
+interface FieldGroupProps {
+  name?: string;
+  collapsible?: boolean;
+  instructions?: string;
+}
+
+export default function FieldGroup(props: PropsWithChildren<FieldGroupProps>) {
+  const { children, name, collapsible = false, instructions } = props;
+  const [collapsed, setCollapsed] = useState(false);
+
+  return (
+    <OuterContainer spacing={4}>
+      <InnerFullWidth>
+        {/* Header */}
+        {name && (
+          <div className="field-margin">
+            {collapsible ? (
+              <span id="field-group-header" className="header-clickable"
+                style={{ cursor: 'pointer' }} onClick={() => setCollapsed(c => !c)}>
+                {collapsed ? <ArrowRightIcon /> : <ArrowDownIcon />}
+                <b>{name}</b>
+              </span>
+            ) : (
+              <b>{name}</b>
+            )}
+          </div>
+        )}
+        {/* Instructions (skip if === 'none') */}
+        {instructions && instructions !== 'none' && (
+          <div className="instruction-text" dangerouslySetInnerHTML={{ __html: instructions }} />
+        )}
+        {/* Children (hidden when collapsed) */}
+        {!collapsed && <div style={{ width: '100%' }}>{children}</div>}
+      </InnerFullWidth>
+    </OuterContainer>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. **State:** Maintain a `collapsed` boolean in local state, initialized to `false` (expanded).

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/design-system-extension-skills/FieldGroupList.md

@@ -24,6 +24,49 @@ Renders a vertical list of field group items. Each item has a bold name header,
 | `onDelete` | `(id: string) => void`                                     | No       | Called with the item's `id` when the delete button is clicked. If not provided, no delete button is shown |
 | `onAdd`    | `() => void`                                               | No       | Called when the "+Add" link is clicked. If not provided, no add link or dividers are shown                |
 
+## Component Skeleton
+
+```typescript
+import { Utils } from '../../helpers/utils';
+
+interface FieldGroupListProps {
+  items: Array<{ name: string; id: string; children: any }>;
+  onDelete?: (id: string) => void;
+  onAdd?: () => void;
+}
+
+export default function FieldGroupList(props: FieldGroupListProps) {
+  const trashIcon = Utils.getImageSrc('trash', Utils.getSDKStaticConentUrl());
+
+  return (
+    <OuterContainer spacing={4}>
+      <InnerFullWidth>
+        <InnerGrid spacing={1}>
+          {props.items.map(item => (
+            <FullWidthItem key={item.name}>
+              <b>{item.name}</b>
+              {props.onDelete && (
+                <button type="button" style={{ float: 'right' }} className="psdk-utility-button"
+                  id={`delete-row-${item.id}`} aria-label="Delete Row"
+                  onClick={() => props.onDelete(item.id)}>
+                  <img className="psdk-utility-card-action-svg-icon" src={trashIcon} />
+                </button>
+              )}
+              {item.children}
+              <br />
+              {props.onAdd && <><Divider /><br /></>}
+            </FullWidthItem>
+          ))}
+          {props.onAdd && (
+            <LinkButton onClick={props.onAdd} style={{ cursor: 'pointer' }}>+Add</LinkButton>
+          )}
+        </InnerGrid>
+      </InnerFullWidth>
+    </OuterContainer>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. Render a `Grid container` with `spacing={4}` and `justifyContent='space-between'` as the outer wrapper.

package/templates/react-sdk-reference/{.github → .ai-common}/skills/design-system-extension-skills/FieldValueList.md

@@ -30,6 +30,52 @@ When no name is provided, only the value is rendered at full width. Used directl
 | `variant` | `string`  | No       | Layout: `'inline'` (default) or `'stacked'`           |
 | `isHtml`  | `boolean` | No       | If `true`, render value as raw HTML (default `false`) |
 
+## Component Skeleton
+
+```typescript
+interface FieldValueListProps {
+  name?: string;
+  value: any;
+  variant?: string;
+  isHtml?: boolean;
+}
+
+export default function FieldValueList({ name, value, variant, isHtml = false }: FieldValueListProps) {
+  // 1. Fallback for empty value
+  const formattedValue = (value === undefined || value === '') ? '---' : value;
+
+  // 2. No-name case: render value only at full width
+  if (!name) {
+    const typography = variant === 'stacked' ? 'h6' : 'body2';
+    return isHtml
+      ? <ValueContainer typography={typography} dangerouslySetInnerHTML={{ __html: formattedValue }} />
+      : <ValueContainer typography={typography}>{formattedValue}</ValueContainer>;
+  }
+
+  // 3. Stacked variant: label on top, larger value below
+  if (variant === 'stacked') {
+    return (
+      <Row direction="column">
+        <Label style={{ paddingBottom: 0 }}>{name}</Label>
+        {isHtml
+          ? <Value typography="h6" style={{ paddingTop: 0 }} dangerouslySetInnerHTML={{ __html: formattedValue }} />
+          : <Value typography="h6" style={{ paddingTop: 0 }}>{formattedValue}</Value>}
+      </Row>
+    );
+  }
+
+  // 4. Inline variant (default): label 4 cols, value 8 cols
+  return (
+    <Row>
+      <Label xs={4}>{name}</Label>
+      {isHtml
+        ? <Value xs={8} dangerouslySetInnerHTML={{ __html: formattedValue }} />
+        : <Value xs={8}>{formattedValue}</Value>}
+    </Row>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. **Empty value fallback:** If `value` is `undefined` or an empty string (`''`), display `'---'` instead.

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

@@ -31,6 +31,73 @@ 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>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### 1. Operator Selection

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

@@ -22,6 +22,26 @@ Renders a card container intended to display an activity feed or comments stream
 | ---------- | ----------- | -------- | ------------------------------------------------------------------------- |
 | `children` | `ReactNode` | No       | Child components (activity stream content) — currently unused in the stub |
 
+## Component Skeleton
+
+Stub implementation — placeholder only.
+
+```typescript
+import type { PropsWithChildren } from 'react';
+
+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>
+  );
+}
+```
+
+> A production implementation would render `props.children` (the activity stream) inside the card body.
+
 > **Note:** The current reference implementation ignores `children` and renders placeholder content. A full implementation would render `children` inside the card body.
 
 ## Behavioral Contract

package/templates/react-sdk-reference/{.github → .ai-common}/skills/design-system-extension-skills/RichTextEditor.md

@@ -38,6 +38,64 @@ The editor is a `forwardRef` component — the ref is connected to the underlyin
 | `onBlur`       | `React.EventHandler<any>` | Yes      | Called when the editor loses focus                                |
 | `onChange`     | `React.EventHandler<any>` | Yes      | Called when the editor content changes                            |
 
+## Component Skeleton
+
+```typescript
+import { forwardRef } from 'react';
+import { useAfterInitialEffect, useConsolidatedRef, useUID } from '@pega/sdk-react';
+
+interface RichTextEditorProps {
+  id?: string; defaultValue: string; label: string; labelHidden: boolean;
+  info?: string; testId?: string; placeholder?: string;
+  disabled: boolean; required: boolean; readOnly: boolean;
+  error: boolean; onBlur: any; onChange: any;
+}
+
+const RichTextEditor = forwardRef((props: RichTextEditorProps, ref) => {
+  const { defaultValue, label, labelHidden, info, testId, placeholder,
+    disabled, required, readOnly, error, onBlur, onChange } = props;
+  const editorRef = useConsolidatedRef(ref);
+  const id = props.id || useUID();
+
+  // 1. Mode transitions after initial mount
+  useAfterInitialEffect([readOnly, disabled], () => {
+    editorRef?.current?.mode?.set(readOnly || disabled ? 'readonly' : 'design');
+  });
+
+  // 2. Read-only mode: static HTML display
+  if (readOnly) {
+    return (
+      <FormWrapper testId={testId} error={error} required={required}>
+        {!labelHidden && <Label>{label}</Label>}
+        <div className="readonly-richtext-editor"
+          dangerouslySetInnerHTML={{ __html: defaultValue || '--' }} />
+        {info && <HelperText>{info}</HelperText>}
+      </FormWrapper>
+    );
+  }
+
+  // 3. Edit mode: TinyMCE (or equivalent) editor
+  //    Key init config: skin (theme-aware), menubar: false, statusbar: false,
+  //    toolbar_location: 'bottom', min_height: 130, plugins: [lists, advlist, autolink, image, link, autoresize]
+  //    toolbar: 'blocks | bold italic strikethrough | bullist numlist outdent indent | link image' (or false if disabled)
+  //    file_picker_callback: creates <input type='file' accept='image/*'>, reads as DataURL, caches blob
+  //    content_style: theme-aware CSS string
+  //    onInit: store editor instance in editorRef.current
+
+  return (
+    <FormWrapper testId={testId} error={error} required={required}>
+      {!labelHidden && <Label>{label}</Label>}
+      <RichTextEditorWidget id={id} initialValue={defaultValue}
+        disabled={disabled} onBlur={onBlur} onEditorChange={onChange}
+        placeholder={placeholder} onInit={(evt, editor) => { editorRef.current = editor; }} />
+      {info && <HelperText>{info}</HelperText>}
+    </FormWrapper>
+  );
+});
+
+export default RichTextEditor;
+```
+
 ## Behavioral Contract
 
 ### 1. Ref Forwarding

package/templates/react-sdk-reference/{.github → .ai-common}/skills/design-system-extension-skills/WssQuickCreate.md

@@ -23,6 +23,37 @@ Renders a titled section of clickable action cards arranged in a responsive CSS
 | `heading` | `string`                                                       | Yes      | Section title rendered as an `<h1>`                                          |
 | `actions` | `Array<{ label: string; onClick: () => void; icon?: string }>` | No       | List of action items; each has a label, click handler, and optional icon URL |
 
+## Component Skeleton
+
+```typescript
+import './WssQuickCreate.css';
+
+interface WssQuickCreateProps {
+  heading: string;
+  actions?: Array<{ label: string; onClick: () => void; icon?: string }>;
+}
+
+export default function WssQuickCreate({ heading, actions }: WssQuickCreateProps) {
+  return (
+    <>
+      <h1 id="quick-links-heading" className="quick-links-heading">{heading}</h1>
+      <ul id="quick-links" className="quick-link-ul-list">
+        {actions?.map((action, index) => (
+          <li key={index} className="quickLinkList">
+            <button type="button" className="quick-link-button" onClick={action.onClick}>
+              <span className="quick-link-button-span">
+                {action.icon && <img className="quick-link-icon" src={action.icon} />}
+                <span>{action.label}</span>
+              </span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. Render the `heading` in an `<h1>` element with `id='quick-links-heading'` and class `quick-links-heading`.

package/templates/react-sdk-reference/{.github → .ai-common}/skills/design-system-extension.md

@@ -221,7 +221,7 @@ DSE components fall into three patterns with different DS dependencies:
 
 The component-specific skill file specifies which pattern applies.
 
-**1. Check the component-specific skill file** — `.github/skills/design-system-extension-skills/<ComponentName>.md` contains a **Design System Mapping** table where available.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` contains a **Design System Mapping** table where available.
 
 **2. If the chosen design system is not listed** — use the component purpose and pattern category above to pick the closest DS primitive.
 

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

@@ -153,7 +153,7 @@ export default function MyField(props: MyFieldProps) {
 
 When filling in the `// [DS RENDER]` section with a specific design system:
 
-**1. Check the component-specific skill file** — `.claude/skills/field-skills/<ComponentName>.md` contains a **Design System Mapping** table that lists the recommended DS component for common design systems. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/field-skills/<ComponentName>.md` contains a **Design System Mapping** table that lists the recommended DS component for common design systems. Use it as a starting point.
 
 **2. If the chosen design system is not in the mapping table** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
 
@@ -181,6 +181,23 @@ grep -A 40 "interface.*Props" <path-to-file>
 
 ## Event Handling
 
+> ⚠️ **CRITICAL — DO NOT DUPLICATE IMPORTS FROM `field-utils`**
+>
+> If the project has a `field-utils.ts` or `field-utils.tsx` file that exports utility functions AND types (e.g., `DynamicFieldProps`, `commitField`, `FieldValue`, `getFieldContext`, `useFieldValue`, `helperText`, `getOptions`), import everything you need in a **single import statement**.
+>
+> ```typescript
+> // ✅ CORRECT — one import for both types and functions
+> import { commitField, DynamicFieldProps, FieldValue, getFieldContext, helperText } from '../field-utils';
+>
+> // ❌ WRONG — duplicate identifier error!
+> import type { DynamicFieldProps } from '../field-utils';
+> import { commitField, DynamicFieldProps, FieldValue, getFieldContext } from '../field-utils';
+> ```
+>
+> TypeScript allows mixing type and value exports in a single import. NEVER add a separate `import type` line for a symbol that is already imported in another import from the same module.
+>
+> **Before writing imports:** Check what `field-utils` exports. If it exports `DynamicFieldProps` as a `type`, you can import it alongside value exports in one statement.
+
 Use `src/components/helpers/event-utils.ts` to commit values to the Pega store:
 
 ```typescript