@pega/sdk 0.0.3 → 0.0.5

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

@@ -1,8 +1,3 @@
----
-description: DSE component skill: Operator
-alwaysApply: false
----
-
 # Skill: Operator
 
 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.
@@ -25,22 +20,90 @@ Renders a clickable read-only field displaying a case operator's name and the re
 
 The component interface extends `PConnProps` but all rendering data is passed as explicit props:
 
-| Prop | 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. |
-| `createDateTime` | `string` | Yes | ISO datetime string of when the case was created |
-| `createLabel` | `string` | Yes | Display label for the create operator field |
-| `createOperator` | `{ userName: string; userId: string }` | Yes | Creator's name and ID |
-| `updateDateTime` | `string` | Yes | ISO datetime string of last update |
-| `updateLabel` | `string` | Yes | Display label for the update operator field |
-| `updateOperator` | `{ userName: string; userId: string }` | Yes | Updater's name and ID |
+| Prop             | 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.                                               |
+| `createDateTime` | `string`                               | Yes      | ISO datetime string of when the case was created                                                                                   |
+| `createLabel`    | `string`                               | Yes      | Display label for the create operator field                                                                                        |
+| `createOperator` | `{ userName: string; userId: string }` | Yes      | Creator's name and ID                                                                                                              |
+| `updateDateTime` | `string`                               | Yes      | ISO datetime string of last update                                                                                                 |
+| `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
 
 Determine which operator to display based on `label.toLowerCase()` or `displayLabel?.toLowerCase()`:
+
 - If either is `'create operator'`:
   - `caseOpLabel = createLabel`
   - `caseOpName = createOperator.userName`
@@ -56,6 +119,7 @@ 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:
+
 - `defaultValue={caseOpName}`
 - `label={caseOpLabel}`
 - `onClick={showOperatorDetails}`
@@ -66,6 +130,7 @@ Below the TextField, render the relative time: `Utils.generateDateTime(caseTime,
 ### 3. Popover on Click (`showOperatorDetails`)
 
 When the TextField is clicked:
+
 1. Call `PCore.getUserApi().getOperatorDetails(caseOpId)` — returns a Promise.
 2. Use `PCore.getLocaleUtils().getLocaleValue(key, 'Operator')` to localize field labels.
 3. On resolution, build a fields array with these entries (using `'---'` as fallback for missing values):
@@ -81,6 +146,7 @@ When the TextField is clicked:
 ### 4. Popover Layout
 
 The popover renders when `popoverAnchorEl` is set:
+
 - Anchor origin: `{ vertical: 'bottom', horizontal: 'center' }`
 - Transform origin: `{ vertical: 'top', horizontal: 'center' }`
 - Max width: `45ch`
@@ -96,20 +162,21 @@ Derived from `Operator.tsx` makeStyles:
 
 ### Root Container
 
-| Property | Value |
-|----------|-------|
-| Padding | `theme.spacing(1)` (≈ 8px) |
-| Margin | `theme.spacing(1)` |
+| Property | Value                      |
+| -------- | -------------------------- |
+| Padding  | `theme.spacing(1)` (≈ 8px) |
+| Margin   | `theme.spacing(1)`         |
 
 ### Popover Container
 
-| Property | Value |
-|----------|-------|
-| Padding | `theme.spacing(1)` |
-| Margin | `theme.spacing(1)` |
-| Max width | 45ch |
+| Property  | Value              |
+| --------- | ------------------ |
+| Padding   | `theme.spacing(1)` |
+| Margin    | `theme.spacing(1)` |
+| Max width | 45ch               |
 
 **CSS-only implementation notes:**
+
 - Main display: read-only text field with label above, value below, pointer cursor on the value element.
 - Time display: secondary muted text below the operator name (e.g., `font-size: 0.75rem; color: var(--text-secondary)`).
 - Popover: `position: absolute; background: var(--bg-paper); border: 1px solid var(--divider); border-radius: 4px; padding: 8px; max-width: 45ch; box-shadow: 0 4px 12px rgba(0,0,0,0.15)`.
@@ -138,15 +205,16 @@ Derived from `Operator.tsx` makeStyles:
 
 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>` |
+| 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

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

@@ -1,8 +1,3 @@
----
-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".
@@ -23,9 +18,29 @@ Renders a card container intended to display an activity feed or comments stream
 
 ## Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `children` | `ReactNode` | No | Child components (activity stream content) — currently unused in the stub |
+| Prop       | Type        | Required | Description                                                               |
+| ---------- | ----------- | -------- | ------------------------------------------------------------------------- |
+| `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.
 
@@ -45,14 +60,15 @@ 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` |
+| 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`.
@@ -74,15 +90,16 @@ Derived from `Pulse.tsx` makeStyles:
 
 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>` |
+| 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/.ai-common/skills/design-system-extension-skills/RichTextEditor.md

@@ -0,0 +1,290 @@
+# 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                            |
+
+## 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
+
+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