@pega/sdk 0.0.4 → 0.0.5

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

@@ -24,6 +24,90 @@ Renders a numeric input for percentage values. Always appends a `%` suffix in th
 | `showGroupSeparators` | `string` (optional) | —       | Whether to show thousands separators (passed as string, truthy check applies)                    |
 | `decimalPrecision`    | `number` (optional) | —       | Number of decimal places                                                                         |
 
+## Component Skeleton
+
+Follow this exact structure. Nearly identical to Currency but with `suffix='%'` instead of prefix, and no `fixedDecimalScale`.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getCurrencyCharacters, getCurrencyOptions } from '../Currency/currency-utils';
+import handleEvent from '../../helpers/event-utils';
+import { format } from '../../helpers/formatters';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface PercentageProps extends PConnFieldProps {
+  currencyISOCode?: string;
+  showGroupSeparators?: string;
+  decimalPrecision?: number;
+}
+
+export default function Percentage(props: PercentageProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, currencyISOCode = 'USD',
+    testId, helperText, displayMode, hideLabel, placeholder,
+    showGroupSeparators, decimalPrecision,
+  } = props;
+
+  // 3. State
+  const [values, setValues] = useState(value.toString());
+
+  // 4. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 5. Formatted value (computed eagerly, before display mode check)
+  const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
+  const formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
+
+  // 6. useEffect: sync from store — deps: [value]
+  useEffect(() => { setValues(value.toString()); }, [value]);
+
+  // 7. Read-only prop
+  let readOnlyProp = {};
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 8. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant="stacked" />;
+  }
+
+  // 9. Test ID + separators (computed AFTER display mode check in actual code)
+  const testProps: any = { 'data-test-id': testId };
+  const theSymbols = getCurrencyCharacters(currencyISOCode);
+  const theCurrDec = theSymbols.theDecimalIndicator;
+  const theCurrSep = theSymbols.theDigitGroupSeparator;
+
+  // 10. Event handlers
+  function PercentageOnBlur() { handleEvent(actions, 'changeNblur', propName, values); }
+  const handleChange = (val) => { setValues(val.value); };
+
+  // 11. Main render — numeric format input with % suffix
+  //     Key props:
+  //     - valueIsNumericString: true, fullWidth: true
+  //     - value: values, suffix: '%'
+  //     - variant: readOnly ? 'standard' : 'outlined'
+  //     - decimalSeparator: theCurrDec
+  //     - thousandSeparator: showGroupSeparators ? theCurrSep : ''
+  //     - decimalScale: decimalPrecision
+  //     - onValueChange, onBlur: !readOnly ? PercentageOnBlur : undefined
+  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //     - required, disabled, error: status === 'error', size: 'small'
+  //     - slotProps: { input: { ...readOnlyProp, inputProps: { ...testProps } } }
+  return <NumericFormatInput ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.

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

@@ -24,6 +24,87 @@ No props beyond `PConnFieldProps`. Import type as:
 import type { PConnFieldProps } from '@pega/sdk-react';
 ```
 
+## Component Skeleton
+
+Follow this exact structure. Replace `<PhoneInputWidget>` with equivalents from your chosen design system / phone library.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import handleEvent from '../../helpers/event-utils';
+
+interface PhoneProps extends PConnFieldProps {}
+
+export default function Phone(props: PhoneProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props — note: onChange is used in readOnly mode
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, onChange, readOnly, testId,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+
+  // 3. PConnect setup
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+
+  // 4. State + sync
+  const [inputValue, setInputValue] = useState(value);
+  useEffect(() => setInputValue(value), [value]);
+
+  // 5. Derived values
+  const helperTextToDisplay = validatemessage || helperText;
+  let testProp = { 'data-test-id': testId };
+
+  // 6. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 7. Read-only return — keeps phone widget but disables dropdown + sets input readOnly
+  //    Uses onChange from PROPS (not local handler), value from PROPS (not state)
+  if (readOnly) {
+    return (
+      <div>
+        <PhoneInputWidget
+          defaultCountry="US" value={value} onChange={onChange}
+          disableDropdown={true}
+          slotProps={{ input: { readOnly: true, ...testProp } }}
+          /* + label, helperText, required, disabled, error, size, placeholder */
+        />
+      </div>
+    );
+  }
+
+  // 8. Editable handlers
+  const handleChange = (inputVal) => { setInputValue(inputVal); };
+  const handleBlur = (event) => {
+    const phoneValue = event?.target?.value;
+    let phoneNumber = phoneValue.split(' ').slice(1).join();
+    phoneNumber = phoneNumber ? `+${phoneValue.replace(/\\D+/g, '')}` : '';
+    handleEvent(actions, 'changeNblur', propName, phoneNumber);
+  };
+
+  // 9. Main render — phone input with country selector
+  //    Key props:
+  //    - fullWidth, variant: 'outlined', size: 'small'
+  //    - defaultCountry: 'US'
+  //    - value: inputValue, onChange: handleChange
+  //    - onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - slotProps: { input: { ...testProp } }
+  return <PhoneInputWidget ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `inputValue` (string). Initialize from `value` prop. `useEffect` watching `value` → `setInputValue(value)`.

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

@@ -30,6 +30,99 @@ Renders a group of radio buttons for single-selection from a list of options. Su
 | `showImageDescription` | `boolean` (optional) | Whether to show image description in cards                                      |
 | `datasource`           | `any` (optional)     | Datasource for card variant                                                     |
 
+## Component Skeleton
+
+Follow this exact structure. Includes localization metadata derivation (same pattern as Dropdown).
+
+```typescript
+import { useState, useEffect } from 'react';
+import Utils from '../../helpers/utils';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface RadioButtonsProps extends PConnFieldProps {
+  inline: boolean;
+  fieldMetadata?: any;
+  variant?: string;
+  hideFieldLabels?: boolean;
+  additionalProps?: any;
+  imagePosition?: string;
+  imageSize?: string;
+  showImageDescription?: boolean;
+  datasource?: any;
+}
+
+export default function RadioButtons(props: RadioButtonsProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+  const SelectableCard = getComponentFromRegistry('SelectableCard');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, value = '', readOnly, validatemessage,
+    helperText, status, required, inline, displayMode, hideLabel,
+    fieldMetadata, variant, hideFieldLabels, additionalProps,
+    datasource, imagePosition, imageSize, showImageDescription,
+  } = props;
+
+  // 3. State
+  const [theSelectedButton, setSelectedButton] = useState(value);
+
+  // 4. PConnect setup
+  const thePConn = getPConnect();
+  const theConfigProps = thePConn.getConfigProps();
+  const actionsApi = thePConn.getActionsApi();
+  const propName = (thePConn.getStateProps() as any).value;
+  const helperTextToDisplay = validatemessage || helperText;
+  const className = thePConn.getCaseInfo().getClassName();
+
+  // 5. Localization keys (same pattern as Dropdown)
+  let configProperty = (thePConn.getRawMetadata() as any)?.config?.value || '';
+  configProperty = configProperty.startsWith('@P') ? configProperty.substring(3) : configProperty;
+  configProperty = configProperty.startsWith('.') ? configProperty.substring(1) : configProperty;
+  const metaData = Array.isArray(fieldMetadata)
+    ? fieldMetadata.filter(f => f?.classID === className)[0] : fieldMetadata;
+  let displayName = metaData?.datasource?.propertyForDisplayText;
+  displayName = displayName?.slice(displayName.lastIndexOf('.') + 1);
+  const localeContext = metaData?.datasource?.tableType === 'DataPage' ? 'datapage' : 'associated';
+  const localeClass = localeContext === 'datapage' ? '@baseclass' : className;
+  const localeName = localeContext === 'datapage' ? metaData?.datasource?.name : configProperty;
+  const localePath = localeContext === 'datapage' ? displayName : localeName;
+
+  // 6. Load options (synchronous)
+  const theOptions = Utils.getOptionList(theConfigProps, thePConn.getDataObject(''));
+
+  // 7. useEffect: sync selected from value — deps: [value]
+  useEffect(() => { setSelectedButton(value); }, [value]);
+
+  // 8. Display mode returns (with localization)
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label}
+      value={thePConn.getLocalizedValue(value, localePath,
+        thePConn.getLocaleRuleNameFromKeys(localeClass, localeContext, localeName))} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') { /* same with variant="stacked" */ }
+
+  // 9. Event handlers
+  const handleChange = (event) => {
+    handleEvent(actionsApi, 'changeNblur', propName, event.target.value);
+  };
+  const handleBlur = (event) => {
+    thePConn.getValidationApi().validate(event.target.value, '');
+  };
+
+  // 10. Card variant return (variant === 'card')
+  //     → heading + grid + SelectableCard with type='radio'
+
+  // 11. Standard variant return
+  //     FormControl > FormLabel > RadioGroup(row={inline}) >
+  //       FormControlLabel per option (localized label) >
+  //     FormHelperText
+  return <RadioGroupWidget ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `theSelectedButton` (string). Initialize from `value` prop. `useEffect` watching `value` → `setSelectedButton(value)`.

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

@@ -22,6 +22,91 @@ Renders a rich text (WYSIWYG) editor for HTML content. Uses a registry-resolved
 | ----------------- | ------------------- | --------------------------------------------- |
 | `additionalProps` | `object` (optional) | Extra props forwarded to the `RichTextEditor` |
 
+## Component Skeleton
+
+Follow this exact structure. The `RichTextEditor` is resolved from the registry — it wraps whatever WYSIWYG library you choose.
+
+```typescript
+import { useRef } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+import './RichText.css';
+
+interface RichTextProps extends PConnFieldProps {
+  additionalProps?: object;
+}
+
+export default function RichText(props: RichTextProps) {
+  // 1. Registry lookups
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+  const RichTextEditor = getComponentFromRegistry('RichTextEditor');
+
+  // 2. Destructure props
+  const {
+    getPConnect, value, placeholder, validatemessage,
+    label, hideLabel, helperText, testId, displayMode, additionalProps,
+  } = props;
+  const pConn = getPConnect();
+  const editorRef: any = useRef(null);
+
+  // 3. Props coercion — Pega may pass 'true'/'false' strings
+  let { readOnly, required, disabled } = props;
+  [readOnly, required, disabled] = [readOnly, required, disabled].map(
+    (prop) => prop === true || (typeof prop === 'string' && prop === 'true'),
+  );
+
+  // 4. Derived
+  const helperTextToDisplay = validatemessage || helperText;
+
+  // 5. Display mode returns — note isHtml prop
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} isHtml />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} isHtml variant="stacked" />;
+  }
+
+  // 6. Read-only render — no onChange/onBlur
+  if (readOnly) {
+    return (
+      <RichTextEditor {...additionalProps}
+        label={label} labelHidden={hideLabel} defaultValue={value}
+        testId={testId} info={helperTextToDisplay} ref={editorRef} readOnly />
+    );
+  }
+
+  // 7. Editable handlers
+  const actionsApi = pConn.getActionsApi();
+  let status = '';
+  if (validatemessage !== '') status = 'error';
+
+  const handleChange = () => {
+    if (status === 'error') {
+      const property = (pConn.getStateProps() as any).value;
+      pConn.clearErrorMessages({ property, category: '', context: '' });
+    }
+  };
+  const handleBlur = () => {
+    if (editorRef.current) {
+      const editorValue = editorRef.current.getContent({ format: 'html' });
+      const property = (pConn.getStateProps() as any).value;
+      handleEvent(actionsApi, 'changeNblur', property, editorValue);
+    }
+  };
+
+  // 8. Editable render
+  return (
+    <RichTextEditor {...additionalProps}
+      label={label} labelHidden={hideLabel} info={helperTextToDisplay}
+      defaultValue={value} placeholder={placeholder}
+      disabled={disabled} required={required} testId={testId}
+      ref={editorRef} error={status === 'error'}
+      onBlur={handleBlur} onChange={handleChange} />
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. **Editor ref:** Maintain an `editorRef` (via `useRef`) — the editor exposes its content via `editorRef.current.getContent({ format: 'html' })`.

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

@@ -35,6 +35,60 @@ import type { PConnProps } from '@pega/sdk-react';
 
 All remaining props (`...restProps`) are forwarded to each child component.
 
+## Component Skeleton
+
+Read-only display component — no state, no event handling.
+
+```typescript
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface ScalarListProps extends PConnProps {
+  displayInModal: boolean;
+  hideLabel: boolean;
+  value: any[];
+  componentType: string;
+  label: string;
+  displayMode: string;
+}
+
+// Local sub-component: renders items as spans in an unstyled list
+function CommaSeparatedList({ items }) {
+  return (
+    <ul style={{ padding: '0', margin: '0' }}>
+      {items.map((value, index) => <span key={index}>{value}</span>)}
+    </ul>
+  );
+}
+
+export default function ScalarList(props: ScalarListProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure — note ...restProps forwarded to each child
+  const { label, getPConnect, componentType, value: scalarValues, displayMode, hideLabel, ...restProps } = props;
+
+  // 3. Create child components for each scalar value
+  const items = scalarValues?.map((scalarValue) =>
+    getPConnect().createComponent(
+      {
+        type: componentType,
+        config: { value: scalarValue, displayMode: 'DISPLAY_ONLY', label, ...restProps, readOnly: 'true' },
+      },
+      '', '', {},  // 2nd/3rd/4th args per typedef
+    ),
+  );
+
+  // 4. Display mode: STACKED_LARGE_VAL or DISPLAY_ONLY → bare list
+  if (['STACKED_LARGE_VAL', 'DISPLAY_ONLY'].includes(displayMode)) {
+    return <div><CommaSeparatedList items={items} /></div>;
+  }
+
+  // 5. Default: wrap in FieldValueList
+  return <FieldValueList name={hideLabel ? '' : label} value={<CommaSeparatedList items={items} />} variant="stacked" />;
+}
+```
+
 ## Behavioral Contract
 
 1. **No state, no event handling** — purely display/read-only.

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

@@ -44,6 +44,61 @@ Renders a grid of selectable cards. Each card contains a radio button or checkbo
 | `setIsRadioCardSelected` | `function`              | —       | Callback to inform parent whether radio selection matched                          |
 | `showNoValue`            | `boolean`               | `false` | When true (read-only + no selected items), render "No Value" text                  |
 
+## Component Skeleton
+
+This component does NOT extend `PConnFieldProps` — it uses raw `props`. No typed interface in the reference implementation.
+
+```typescript
+import { resolveReferenceFields } from './utils';
+
+export default function SelectableCard(props) {
+  // 1. Destructure all props (image is a nested object)
+  const {
+    getPConnect, type,
+    image: { imagePosition, imageSize, showImageDescription, imageField = '', imageDescription = '' },
+    dataSource, recordKey = '', className, cardLabel,
+    hideFieldLabels = false, readOnly, disabled,
+    readOnlyList = [], displayMode, radioBtnValue,
+    onChange, onBlur, onClick, onKeyDown,
+    additionalProps, testId, setIsRadioCardSelected, showNoValue = false,
+  } = props;
+  const pConn = getPConnect();
+
+  // 2. "No Value" guard
+  if (showNoValue) return <Typography>No Value</Typography>;
+
+  // 3. Data source selection
+  const cardDataSource = (readOnly || displayMode === 'DISPLAY_ONLY')
+    ? readOnlyList || [] : dataSource?.source;
+  const imageDescriptionKey = showImageDescription ? imageDescription : undefined;
+
+  // 4. Card click handler — makes entire card clickable
+  const handleCardClick = (event) => {
+    if (disabled || readOnly) return;
+    if (event.target.closest?.('label, input')) return;
+    const input = event.currentTarget.querySelector('input[type="radio"], input[type="checkbox"]');
+    if (input) input.click();
+  };
+
+  // 5. Track radio selection state
+  let radioItemSelected = false;
+
+  // 6. Map cards
+  return (
+    <>
+      {(cardDataSource || []).map((item) => {
+        const resolvedFields = resolveReferenceFields(item, hideFieldLabels, recordKey, pConn);
+        // Build image object if item[imageField] exists
+        // Display mode: render simple read-only card (no input)
+        // Editable mode: render card with Radio or Checkbox inside
+        // Track: if type==='radio' && radioBtnValue === item[recordKey], radioItemSelected=true
+      })}
+      {type === 'radio' && setIsRadioCardSelected && setIsRadioCardSelected(radioItemSelected)}
+    </>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### Data source selection

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

@@ -30,6 +30,70 @@ Renders a clickable link (`<a>` or button-style link) that navigates to a Pega c
 | `dataRelationshipContext` | `string \| null`  | `null`  | Context for data relationship resolution                                           |
 | `contextPage`             | `any`             | —       | Context page with `classID`                                                        |
 
+## Component Skeleton
+
+This component computes a URL and renders a clickable link. Most logic is URL resolution — no form state.
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+import semanticUtils from './utils';
+
+interface SemanticLinkProps extends PConnFieldProps {
+  text: string;
+  resourcePayload: any;
+  resourceParams: any;
+  previewKey: string | null;
+  onClick: (event: any) => void;
+  testId: string;
+  referenceType: string | null;
+  dataRelationshipContext: string | null;
+  contextPage: any;
+}
+
+export default function SemanticLink(props: SemanticLinkProps) {
+  // 1. Destructure (note: onClick is received but NOT used directly)
+  const {
+    text, resourcePayload = {}, resourceParams = {},
+    getPConnect, previewKey, onClick, testId = '',
+    referenceType, dataRelationshipContext = null, contextPage,
+    ...restProps
+  } = props;
+
+  // 2. Constants
+  const { ACTION_OPENWORKBYHANDLE, ACTION_SHOWDATA } = PCore.getSemanticUrlUtils().getActions();
+  const pConnect = getPConnect();
+  const { RESOURCE_TYPES: { DATA }, WORKCLASS, CASE_INFO: { CASE_INFO_CLASSID } } = PCore.getConstants();
+
+  // 3. URL resolution variables
+  let linkURL = '';
+  let payload = {};
+  let dataViewName;
+  let isData = false;
+
+  // 4. Determine reference type and resolve URL
+  //    → see Behavioral Contract "URL Resolution"
+
+  // 5. showDataAction() — calls getPConnect().getActionsApi().showData(...)
+  //    → see Behavioral Contract
+
+  // 6. openLinkClick(e) — click handler
+  //    If !metaKey && !ctrlKey: preventDefault, then showDataAction or openWorkByHandle
+  //    If metaKey/ctrlKey: let browser open href in new tab
+
+  // 7. Render link
+  return (
+    <LinkComponent
+      href={linkURL}
+      onClick={openLinkClick}
+      data-testid={testId}
+      {...restProps}
+    >
+      {text || '--'}
+    </LinkComponent>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### URL Resolution

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

@@ -28,6 +28,72 @@ All other props come from `PConnFieldProps`. Import type as:
 import type { PConnFieldProps } from '@pega/sdk-react';
 ```
 
+## Component Skeleton
+
+Similar to TextInput but multiline with fixed rows. Does NOT delegate to TextInput in read-only mode.
+
+```typescript
+import { useEffect, useState } from 'react';
+import handleEvent from '../../helpers/event-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnFieldProps } from '@pega/sdk-react';
+
+interface TextAreaProps extends PConnFieldProps {
+  fieldMetadata?: any;
+}
+
+export default function TextArea(props: TextAreaProps) {
+  // 1. Registry lookup
+  const FieldValueList = getComponentFromRegistry('FieldValueList');
+
+  // 2. Destructure props
+  const {
+    getPConnect, label, required, disabled, value = '',
+    validatemessage, status, readOnly, testId, fieldMetadata,
+    helperText, displayMode, hideLabel, placeholder,
+  } = props;
+  const helperTextToDisplay = validatemessage || helperText;
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const propName = (pConn.getStateProps() as any).value;
+  const maxLength = fieldMetadata?.maxLength;
+
+  // 3. State
+  const [inputValue, setInputValue] = useState('');
+  let readOnlyProp = {};
+
+  // 4. useEffect: sync from store — deps: [value]
+  useEffect(() => { setInputValue(value); }, [value]);
+
+  // 5. Display mode returns
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} />;
+  }
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return <FieldValueList name={hideLabel ? '' : label} value={value} variant="stacked" />;
+  }
+
+  // 6. Read-only: set readOnlyProp (do NOT delegate to TextInput — preserve multiline)
+  if (readOnly) readOnlyProp = { readOnly: true };
+
+  // 7. Test ID + handlers
+  const testProps: any = { 'data-test-id': testId };
+  function handleChange(event) { setInputValue(event?.target?.value); }
+  function handleBlur() { handleEvent(actions, 'changeNblur', propName, inputValue); }
+
+  // 8. Main render — multiline text input
+  //    Key props:
+  //    - multiline: true, minRows: 5, maxRows: 5
+  //    - fullWidth, variant: readOnly ? 'standard' : 'outlined', size: 'small'
+  //    - value: inputValue, onChange: handleChange
+  //    - onBlur: !readOnly ? handleBlur : undefined
+  //    - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
+  //    - required, disabled, error: status === 'error'
+  //    - slotProps: { input: { ...readOnlyProp, inputProps: { maxLength, ...testProps } } }
+  return <TextAreaWidget ... />;
+}
+```
+
 ## Behavioral Contract
 
 1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `''`.

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

@@ -34,6 +34,34 @@ interface TextContentProps extends PConnProps {
 | `content`   | `string`                                                                  | The text string to render                         |
 | `displayAs` | `'Paragraph' \| 'Heading 1' \| 'Heading 2' \| 'Heading 3' \| 'Heading 4'` | How to render the text — maps to typography level |
 
+## Component Skeleton
+
+Simplest possible component — no state, no effects, just a switch on `displayAs`.
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+
+interface TextContentProps extends PConnProps {
+  content: string;
+  displayAs: 'Paragraph' | 'Heading 1' | 'Heading 2' | 'Heading 3' | 'Heading 4';
+}
+
+export default function TextContent(props: TextContentProps) {
+  const { content, displayAs } = props;
+
+  switch (displayAs) {
+    case 'Paragraph': return <p>{content}</p>;
+    case 'Heading 1': return <h1>{content}</h1>;
+    case 'Heading 2': return <h2>{content}</h2>;
+    case 'Heading 3': return <h3>{content}</h3>;
+    case 'Heading 4': return <h4>{content}</h4>;
+    default:
+      console.error(`TextContent got unexpected displayAs: ${displayAs}`);
+      return <p>{content}</p>;
+  }
+}
+```
+
 ## Behavioral Contract
 
 1. **No state, no effects** — purely presentational. Render `content` using the appropriate typography element for `displayAs`.