@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/Pulse.mdrules

@@ -0,0 +1,88 @@
+---
+description: DSE component skill: Pulse
+alwaysApply: false
+---
+
+# Skill: Pulse
+
+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.
+
+---
+
+## Component Purpose
+
+Renders a card container intended to display an activity feed or comments stream for a Pega case. The current reference implementation is a **stub** — it renders only a Card with the title "Pulse" and placeholder body text. A production implementation would render a real activity feed stream inside the card using the `children` slot.
+
+## Pega Metadata
+
+- **Pega Name:** `Pulse`
+- **Registration key:** `Pulse` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives children via `PropsWithChildren`
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode` | No | Child components (activity stream content) — currently unused in the stub |
+
+> **Note:** The current reference implementation ignores `children` and renders placeholder content. A full implementation would render `children` 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`).
+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).
+
+> **Stub note:** Steps 2–3 are placeholder content. In a real implementation, the card header would show a section label and the card body would render the `children` activity stream.
+
+## Visual Specifications
+
+Derived from `Pulse.tsx` makeStyles:
+
+### 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) |
+
+**CSS-only implementation notes:**
+- Card wrapper: `margin-top: 8px; margin-bottom: 8px; border-left: 6px solid var(--app-primary-light-color); border-radius: 4px; box-shadow: 0 1px 3px rgba(0,0,0,0.12)`.
+- Card header: `padding: 16px; font-size: 1.25rem; font-weight: 500`.
+- Card body: `padding: 0 16px 16px`.
+- Use a CSS variable `--app-primary-light-color` for the accent border color.
+
+## 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).
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+
+## Design System Mapping
+
+**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 header title typography → design system's heading variant (h6 or equivalent)

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/RichTextEditor.mdrules

@@ -0,0 +1,211 @@
+---
+description: DSE component skill: RichTextEditor
+alwaysApply: false
+---
+
+# Skill: RichTextEditor
+
+WYSIWYG rich text editor field backed by TinyMCE. Supports editable and read-only modes, optional label, helper text, error/required states, and a file picker for image uploads.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a rich text editing area (WYSIWYG) for Pega case properties that store HTML content. In **edit mode**, uses TinyMCE with a bottom toolbar. In **read-only mode**, renders the HTML content as a read-only `<div>`. Wraps the editor in a `FormControl` with an optional floating label and helper text, consistent with other field components.
+
+The editor is a `forwardRef` component — the ref is connected to the underlying TinyMCE editor instance.
+
+> **Note:** TinyMCE is the reference editor library. In non-MUI or non-TinyMCE implementations, this component can be replaced with an alternative rich text library (Quill, ProseMirror, Slate.js, etc.). The behavioral contract below remains the same regardless of library.
+
+## Pega Metadata
+
+- **Pega Name:** `RichTextEditor`
+- **Registration key:** `RichTextEditor` (in `component-map.ts`)
+- **Does NOT extend PConnProps** — receives all data as explicit field-like props
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | No | DOM id for the editor element. Defaults to a generated UID |
+| `defaultValue` | `string` | Yes | Initial HTML content of the editor |
+| `label` | `string` | Yes | Field label displayed above the editor |
+| `labelHidden` | `boolean` | Yes | If `true`, hide the label |
+| `info` | `string` | No | Helper text displayed below the editor |
+| `testId` | `string` | No | Value for `data-test-id` attribute on the FormControl wrapper |
+| `placeholder` | `string` | No | Placeholder text shown in empty editor |
+| `disabled` | `boolean` | Yes | If `true`, editor is in read-only/disabled mode with no toolbar |
+| `required` | `boolean` | Yes | If `true`, marks the field as required |
+| `readOnly` | `boolean` | Yes | If `true`, render as static HTML display (not interactive editor) |
+| `error` | `boolean` | Yes | If `true`, applies error styling to the FormControl |
+| `onBlur` | `React.EventHandler<any>` | Yes | Called when the editor loses focus |
+| `onChange` | `React.EventHandler<any>` | Yes | Called when the editor content changes |
+
+## Behavioral Contract
+
+### 1. Ref Forwarding
+
+The component uses `forwardRef`. Internally, use `useConsolidatedRef(ref)` from `@pega/sdk-react` to create `editorRef` — the TinyMCE editor instance is stored here after initialization.
+
+### 2. UID for id
+
+If `id` is not provided, generate one using `useUID()` from `@pega/sdk-react`.
+
+### 3. Read-Only Mode
+
+If `readOnly` is `true`, render:
+```
+<div
+  key={id}
+  id={id}
+  className='readonly-richtext-editor'
+  dangerouslySetInnerHTML={{ __html: defaultValue || '--' }}
+/>
+```
+Skip the TinyMCE Editor entirely in this case.
+
+### 4. Edit Mode (TinyMCE)
+
+When `readOnly` is `false`, render `<Editor>` from `@tinymce/tinymce-react` with:
+
+| Config | Value |
+|--------|-------|
+| `tinymceScriptSrc` | `'tinymce/tinymce.min.js'` (local script) |
+| `id` | The resolved `id` |
+| `initialValue` | `defaultValue` |
+| `disabled` | `disabled` prop |
+| `onBlur` | `onBlur` prop |
+| `onEditorChange` | `onChange` prop |
+| `onInit` | Store editor in `editorRef.current` |
+
+### 5. TinyMCE `init` Configuration
+
+| Option | Value |
+|--------|-------|
+| `skin` | `'oxide-dark'` (dark mode) / `'oxide'` (light mode) — detect from theme |
+| `menubar` | `false` |
+| `statusbar` | `false` |
+| `branding` | `false` |
+| `min_height` | `130` |
+| `toolbar_location` | `'bottom'` |
+| `plugins` | `['lists', 'advlist', 'autolink', 'image', 'link', 'autoresize']` |
+| `autoresize_bottom_margin` | `0` |
+| `toolbar` | `'blocks \| bold italic strikethrough \| bullist numlist outdent indent \| link image'` (or `false` when `disabled`) |
+| `paste_data_images` | `true` |
+| `file_picker_types` | `'image'` |
+| `file_picker_callback` | See file picker section below |
+| `content_style` | Theme-aware CSS string (see below) |
+| `placeholder` | `placeholder` prop |
+
+### 6. Theme-Aware Content Style
+
+Inject a `content_style` string that uses theme values for the editor body:
+```css
+body {
+  font-family: <theme.typography.fontFamily>;
+  font-size: <theme.typography.fontSize>px;
+  color: <theme.palette.text.primary>;
+  background: <theme.palette.background.paper>;
+}
+a { color: <theme.palette.primary.main>; }
+h1-h6 { color: <theme.palette.text.primary>; font-family: <theme.typography.fontFamily>; }
+blockquote { color: <theme.palette.text.secondary>; border-left: 4px solid <theme.palette.primary.light>; padding-left: 8px; }
+ul, ol { color: <theme.palette.text.primary>; }
+input, textarea, select {
+  background: <theme.palette.background.paper>;
+  color: <theme.palette.text.primary>;
+  border: 1px solid <theme.palette.divider>;
+  border-radius: 4px; padding: 6px 10px; font-size: 1em; font-family: inherit;
+}
+.mce-content-body[data-mce-placeholder]:not(.mce-visualblocks)::before {
+  color: <theme.palette.text.secondary>; opacity: 0.7;
+}
+```
+
+### 7. File Picker Callback
+
+When a user clicks the image upload in the toolbar:
+1. Create a hidden `<input type='file' accept='image/*'>`.
+2. On file selected: read as DataURL using `FileReader`.
+3. On `FileReader.load`: create a blob in TinyMCE's blob cache (`editorRef.current.editorUpload.blobCache`), then call `cb(blobInfo.blobUri(), { title: file.name })`.
+4. Programmatically click the input to open the file dialog.
+
+### 8. readOnly/disabled Transition (after initial mount)
+
+Use `useAfterInitialEffect([readOnly, disabled])` from `@pega/sdk-react`:
+```
+editorRef?.current.mode.set(readOnly || disabled ? 'readonly' : 'design')
+```
+This switches the TinyMCE mode without re-mounting the editor.
+
+### 9. Wrapper Structure
+
+```
+<FormControl variant='standard' data-test-id={testId} error={error} required={required}>
+  {!labelHidden && <InputLabel className='fieldLabel'>{label}</InputLabel>}
+  {richTextComponent}   ← either readOnly div or <Editor>
+  {info && <FormHelperText>{info}</FormHelperText>}
+</FormControl>
+```
+
+## Visual Specifications
+
+Derived from `RichTextEditor.tsx` makeStyles:
+
+### Label
+
+| Property | Value |
+|----------|-------|
+| Position | relative |
+| Transform | `translate(0, 0px) scale(1)` (non-floating — stays at top) |
+| Margin bottom | 5px |
+| Color | `theme.palette.text.secondary` |
+
+**CSS-only implementation notes:**
+- Label: `display: block; font-size: 0.875rem; color: var(--text-secondary); margin-bottom: 5px`.
+- Editor container: `min-height: 130px; border: 1px solid var(--divider); border-radius: 4px`.
+- Toolbar (if CSS-only): render buttons at bottom of the editor area.
+- Read-only display: `div.readonly-richtext-editor { padding: 8px; min-height: 130px; background: var(--bg-paper); color: var(--text-primary) }`.
+- Error state: `border-color: var(--error-color)`.
+- Helper text: `font-size: 0.75rem; color: var(--text-secondary); margin-top: 4px`.
+- Error helper text: `color: var(--error-color)`.
+
+## Edge Cases & Special Logic
+
+- `defaultValue` in read-only mode falls back to `'--'` if empty.
+- `readOnly` and `disabled` are both handled — `readOnly` suppresses the editor entirely; `disabled` keeps the editor mounted but in TinyMCE's `readonly` mode with no toolbar.
+- Mode transitions (readOnly/disabled changing after mount) use `useAfterInitialEffect` — this hook fires on updates but NOT on the initial render, preventing a double-set on mount.
+- The file picker creates a transient `<input type='file'>` element that is never appended to the DOM — it is clicked programmatically.
+- `id` must be stable across renders — use `useUID()` only as a fallback when `id` prop is absent.
+
+## Dependencies
+
+- `Editor` from `@tinymce/tinymce-react` — TinyMCE React wrapper (can be swapped for Quill, ProseMirror, Slate.js, etc.)
+- `useAfterInitialEffect`, `useConsolidatedRef`, `useUID` from `@pega/sdk-react` — SDK hooks
+- `useTheme` from `@mui/material` — for theme-aware content styles
+- `FormControl`, `FormHelperText`, `InputLabel` from `@mui/material` — wrapper structure
+
+## Design System Mapping
+
+**UI control type:** Rich text / WYSIWYG editor field with label, helper text, and error state.
+
+Listed design systems are examples only.
+
+| Design System | Rich Text Library |
+|---|---|
+| Default (CSS only) | `contenteditable` div with custom toolbar, or `<textarea>` |
+| MUI | TinyMCE (`@tinymce/tinymce-react`) wrapped in `<FormControl>` |
+| Ant Design | Quill (`react-quill`) or TinyMCE inside an `<AntForm.Item>` |
+| Chakra UI | Quill or Slate.js inside a `<FormControl>` |
+| Shadcn/ui | Tiptap (`@tiptap/react`) inside a field wrapper |
+
+When implementing in a specific design system, map the following:
+- `defaultValue` → initial HTML content
+- `readOnly={true}` → always render as static HTML `<div>` (no editor instance)
+- `disabled={true}` → editor mounted but read-only (toolbar hidden)
+- `onBlur` / `onChange` → editor's blur and content-change callbacks
+- `error` + `info` → FormControl error state + helper/description text below
+- `labelHidden` → conditionally render the label element
+- File picker → `<input type='file' accept='image/*'>` triggered programmatically

package/templates/react-sdk-reference/.cursor/rules/skills/design-system-extension-skills/WssQuickCreate.mdrules

@@ -0,0 +1,140 @@
+---
+description: DSE component skill: WssQuickCreate
+alwaysApply: false
+---
+
+# Skill: WssQuickCreate
+
+Quick-launch action grid that displays a heading and a set of labeled buttons, each optionally with an icon, for creating WSS cases.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a titled section of clickable action cards arranged in a responsive CSS grid. Each card contains an optional icon image and a label. Used in workspace/portal contexts to provide quick access to case creation actions.
+
+## Pega Metadata
+
+- **Pega Name:** `WssQuickCreate`
+- **Registration key:** `WssQuickCreate` (in `component-map.ts`)
+- **Does NOT use `getPConnect`** — receives all data as direct props
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `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 |
+
+## Behavioral Contract
+
+1. Render the `heading` in an `<h1>` element with `id='quick-links-heading'` and class `quick-links-heading`.
+2. Render a `<ul>` with `id='quick-links'` and class `quick-link-ul-list`.
+3. If `actions` is provided, iterate and render one `<li>` per action.
+4. Each `<li>` has the `quickLinkList` style class (styled card with border, rounded corners, and background color).
+5. Inside each `<li>`, render a `<button>` with class `quick-link-button` and the action's `onClick` handler.
+6. Button content is a `<span class='quick-link-button-span'>` (column flex layout) containing:
+   - If `action.icon` is provided: `<img class='quick-link-icon' src={action.icon} />`
+   - `<span>{action.label}</span>`
+7. If `actions` is not provided or is empty, render only the heading with an empty list.
+
+## Visual Specifications
+
+Derived from `WssQuickCreate.css` and component makeStyles:
+
+### Section Heading
+
+| Property | Value |
+|----------|-------|
+| Tag | `<h1>` |
+| Margin top | 8px |
+
+### Action List
+
+| Property | Value |
+|----------|-------|
+| List style | none |
+| Padding | 0 |
+| Display | grid |
+| Grid template columns | `repeat(auto-fit, minmax(min(20ch, 100%), 1fr))` (responsive columns) |
+| Gap | 1rem |
+
+### Action Card (`<li>`)
+
+| Property | Value |
+|----------|-------|
+| Background (light mode) | `var(--link-button-color)` |
+| Background (dark mode) | `var(--app-background-color)` |
+| Text color | `var(--app-text-color)` |
+| Border radius | 16px |
+| Border | `1px solid var(--app-primary-color)` |
+
+### Action Button
+
+| Property | Value |
+|----------|-------|
+| Text transform | capitalize |
+| Font size | 16px |
+| Color | `var(--app-text-color)` |
+| Height | 10rem |
+| Width | 100% |
+| Background | transparent (inherits card) |
+
+### Button Inner Span
+
+| Property | Value |
+|----------|-------|
+| Display | flex |
+| Flex direction | column |
+| Align items | center |
+| Gap | 0.5rem |
+
+### Icon
+
+| Property | Value |
+|----------|-------|
+| Flex shrink | 0 |
+| Object fit | contain |
+| Width | 3rem |
+| Height | 3rem |
+
+**CSS-only implementation notes:**
+- Action list: `list-style: none; padding: 0; display: grid; grid-template-columns: repeat(auto-fit, minmax(min(20ch, 100%), 1fr)); gap: 1rem`.
+- Action card: `background: var(--link-button-color); border-radius: 16px; border: 1px solid var(--app-primary-color); color: var(--app-text-color)`.
+- Button: `width: 100%; height: 10rem; background: transparent; border: none; cursor: pointer; text-transform: capitalize; font-size: 16px; color: inherit`.
+- Button content: `display: flex; flex-direction: column; align-items: center; gap: 0.5rem`.
+- Icon: `width: 3rem; height: 3rem; object-fit: contain; flex-shrink: 0`.
+
+## Edge Cases & Special Logic
+
+- If `actions` is `undefined` or empty, render the heading and empty `<ul>` without errors.
+- If `action.icon` is `undefined` or an empty string, render only the label span (no `<img>` element).
+- Labels are displayed as-is (no truncation); the grid layout handles responsive sizing naturally.
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+- Icon images are passed as URLs (strings) via `action.icon` — no internal icon system used
+
+## Design System Mapping
+
+**UI control type:** Responsive grid of action cards / quick-launch buttons.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | CSS grid `<ul>` + `<button>` cards with flex icon/label layout |
+| MUI | `<Button>` inside Grid items; use `makeStyles` or `sx` for card styling |
+| Ant Design | `<List>` with `<Card>` items or `<Button>` blocks inside a CSS grid |
+| Chakra UI | `<SimpleGrid>` with `<Button>` children; `flexDir='column'` |
+| Shadcn/ui | Grid of custom `<Button variant='outline'>` cards |
+
+When implementing in a specific design system, map the following:
+- Card border/background → design system's card or outlined button variant
+- Button `onClick` → standard click handler prop
+- Icon + label stacked layout → `flexDirection: 'column'` button content
+- Responsive grid → design system's grid or `SimpleGrid` equivalent