@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/field-skills/SelectableCard.md

@@ -0,0 +1,155 @@
+# Skill: SelectableCard
+
+Card-style radio or checkbox selection grid with optional image support.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders a grid of selectable cards. Each card contains a radio button or checkbox (depending on `type`), a label, optional image, and optional additional fields. Cards are clickable — clicking anywhere on the card triggers the input. Used by `RadioButtons` (variant='card') and `Checkbox` (variant='card').
+
+## Pega Metadata
+
+- **Pega Name:** `SelectableCard`
+- **Type / Subtype:** Internal design system extension
+- **Registration key:** `SelectableCard` (in the project's component map)
+
+> This component does NOT have a metadata file and does NOT extend the project's field input contract — it's a design system component used internally by `RadioButtons` and `Checkbox`.
+
+## Inputs
+
+| Prop                     | Type                    | Default | Description                                                                        |
+| ------------------------ | ----------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `getPConnect`            | `function`              | —       | PConnect accessor                                                                  |
+| `type`                   | `'radio' \| 'checkbox'` | —       | Selection type                                                                     |
+| `image`                  | `object`                | —       | `{ imagePosition, imageSize, showImageDescription, imageField, imageDescription }` |
+| `dataSource`             | `any`                   | —       | Source of card data (in editable mode)                                             |
+| `recordKey`              | `string`                | `''`    | The key field name in each record (e.g., `'pyID'`)                                 |
+| `className`              | `string`                | —       | CSS class for the card                                                             |
+| `cardLabel`              | `string`                | —       | The field name to use as card title                                                |
+| `hideFieldLabels`        | `boolean`               | `false` | Hide field labels inside cards                                                     |
+| `readOnly`               | `boolean`               | —       | Read-only mode                                                                     |
+| `disabled`               | `boolean`               | —       | Disabled state                                                                     |
+| `readOnlyList`           | `any[]`                 | `[]`    | Selected items for read-only display                                               |
+| `displayMode`            | `string`                | —       | Display mode string                                                                |
+| `radioBtnValue`          | `any`                   | —       | Currently selected value (radio mode)                                              |
+| `onChange`               | `function`              | —       | Change handler                                                                     |
+| `onBlur`                 | `function`              | —       | Blur handler                                                                       |
+| `onClick`                | `function`              | —       | Click handler                                                                      |
+| `onKeyDown`              | `function`              | —       | KeyDown handler                                                                    |
+| `additionalProps`        | `any`                   | —       | Spread onto the radio/checkbox input                                               |
+| `testId`                 | `string`                | —       | Test identifier                                                                    |
+| `setIsRadioCardSelected` | `function`              | —       | Callback to inform parent whether radio selection matched                          |
+| `showNoValue`            | `boolean`               | `false` | When true (read-only + no selected items), render "No Value" text                  |
+
+## Implementation Structure
+
+This component does NOT extend the project's field input contract — it defines its own inputs directly.
+
+**Module Setup:** The component depends on two local helper functions:
+
+1. **`prepareComponentInCaseSummary(pConnectMeta, getPConnect)`** — creates a display-only component from field metadata. Receives the field's metadata object (containing `config`, `type`, and optional `children`) and a `getPConnect` function. Resolves the field label via `getPConnect().resolveConfigProps({ label: config.label })`, then creates the field component via `getPConnect().createComponent({ type, children, config })`. Sets `displayMode` to `'DISPLAY_ONLY'` and `readOnly` to `true` on the created component's inherited props. Returns `{ name, value }` where `name` is the resolved label string and `value` is the created component (a renderable UI node).
+
+2. **`resolveReferenceFields(item, hideFieldLabels, recordKey, pConnect)`** — resolves additional display fields for a card record using the PConnect presets pattern. Gets `presets` from `pConnect.getRawMetadata().config.presets`, then extracts field definitions from `presets[0].children[0].children` (limiting to a maximum of 5 fields). For each field preset, creates a PConnect configuration with `meta` set to the preset (with `displayMode: 'DISPLAY_ONLY'` and `contextName` from the parent PConnect added to `config`) and `useCustomContext` set to the current data item. Calls `PCore.createPConnect(fieldMeta)` to create a live PConnect instance for that field, retrieves its metadata via `configObj.getPConnect().getMetadata()`, then passes it to `prepareComponentInCaseSummary` to obtain the rendered component. Returns an array of objects: when `hideFieldLabels` is true, each entry is `{ id, value }`; otherwise `{ id, name, value, type }` — where `id` is a unique string combining `item[recordKey]` and the field index, `name` is the resolved label, `value` is the rendered field component, and `type` is the preset's field type string.
+
+**Main Component Logic** — steps in order:
+
+1. **Receive all inputs** (`image` is a nested object) — `getPConnect`, `type`; from `image` receive `imagePosition`, `imageSize`, `showImageDescription`, `imageField` (default `''`), `imageDescription` (default `''`); also `dataSource`, `recordKey` (default `''`), `className`, `cardLabel`, `hideFieldLabels` (default `false`), `readOnly`, `disabled`, `readOnlyList` (default `[]`), `displayMode`, `radioBtnValue`, `onChange`, `onBlur`, `onClick`, `onKeyDown`, `additionalProps`, `testId`, `setIsRadioCardSelected`, `showNoValue` (default `false`); also `pConn` via `getPConnect()`.
+2. **"No Value" guard** — when `showNoValue` is true, return a text element reading "No Value" and stop.
+3. **Data source selection** — `cardDataSource` is `readOnlyList` (or `[]`) when `readOnly` or `displayMode === 'DISPLAY_ONLY'`, otherwise `dataSource?.source`; `imageDescriptionKey` is `imageDescription` when `showImageDescription` is true, otherwise `undefined`.
+4. **Card click handler** (`handleCardClick`) — makes the entire card clickable: returns early when `disabled || readOnly`; returns early when the click target is inside a `label` or `input` (native click already handled); otherwise finds the radio/checkbox input inside the current card and programmatically clicks it.
+5. **Track radio selection state** — a local `radioItemSelected` flag, initialized to `false`.
+6. **Map cards** — render a container iterating `cardDataSource ?? []`; for each `item`, resolve additional fields via `resolveReferenceFields(item, hideFieldLabels, recordKey, pConn)` (which returns an array of objects with rendered component values), build an image object when `item[imageField]` exists, and branch: in display mode render a simple read-only card (no input); in editable mode render a card containing a `Radio` or `Checkbox` control; render each resolved field's `value` directly (it is a renderable component node, NOT a plain string); while iterating, when `type === 'radio'` and `radioBtnValue === item[recordKey]`, set `radioItemSelected = true`. After the loop, when `type === 'radio'` and `setIsRadioCardSelected` is provided, call `setIsRadioCardSelected(radioItemSelected)`.
+
+## Behavioral Contract
+
+### Data source selection
+
+`cardDataSource` is `readOnlyList` (or `[]` if empty) when `readOnly` or `displayMode === 'DISPLAY_ONLY'`; otherwise it is `dataSource?.source`.
+
+### "No Value" guard
+
+If `showNoValue`: render a plain text element showing `'No Value'` and return early.
+
+### Card click handler
+
+Cards should be clickable anywhere (not just on the checkbox/radio): the handler returns early when `disabled` or `readOnly` is set; it also returns early when the click target is inside a `label` or `input` element (the native click is already handled in that case); otherwise it locates the radio or checkbox input within the current card element and programmatically clicks it.
+
+### Subsection: Display mode (`displayMode === 'DISPLAY_ONLY'`)
+
+Render a **simple read-only card** (no radio/checkbox) containing, in a flex-row layout: an optional image, the card title (`item[cardLabel]`), and the additional resolved fields (from `resolveReferenceFields`). Each field's `value` is a rendered component node — render it directly (do NOT stringify it). If `field.name` is present, render it as a label alongside the value.
+
+### Subsection: Editable mode (radio or checkbox)
+
+Render a **selectable card** wrapped in a container with top padding, with a pointer cursor, full height, and a column flex direction, and a click handler (`handleCardClick`) on the card itself. Inside, the card content area (styled per the image layout table below) contains: an optional image section (full width, 16:9 aspect ratio, contained) shown for inline positions at roughly 40% width; a content section at roughly 60% width containing either a radio control (`value={item[recordKey]}`, `checked={radioBtnValue === item[recordKey]}`, `onChange`) or a checkbox control (`id={item[recordKey]}`, `checked` computed by checking whether `readOnlyList` contains an entry matching `item[recordKey]`, `onChange`), each labeled with `item[cardLabel]`; and finally the list of additional resolved fields, each rendered with its field name (if present) alongside its value (a rendered component node). Unless the field's `type` is `'TextArea'`, lay out each field entry as a two-column grid (label in one column, rendered component in the other).
+
+### Image layout (inline positions)
+
+| `imagePosition`  | CardContent style                           | Image section width | Content section width |
+| ---------------- | ------------------------------------------- | ------------------- | --------------------- |
+| `'inline-start'` | `display: flex`                             | 40%                 | 60%                   |
+| `'inline-end'`   | `display: flex, flexDirection: row-reverse` | 40%                 | 60%                   |
+| block (default)  | default                                     | full width          | full width            |
+
+### Image element
+
+**Visual-only styling notes:** The image spans the full width of its container with a transparent background, a 16:9 aspect ratio, and is constrained to the container's max height/width while using `object-fit: contain` so it scales without distortion.
+
+### Field display layout
+
+**Visual-only styling notes:** Each additional field in editable mode uses a small font size and a small margin; unless the field type is `TextArea`, it is laid out as a two-column grid (label in one column, value in the other).
+
+### Radio tracking
+
+While iterating cards, if `type === 'radio'` and `radioBtnValue === item[recordKey]` for the current item, set `radioItemSelected = true`. After the loop completes, if `setIsRadioCardSelected` is provided, call it with the final `radioItemSelected` value.
+
+## Display Mode Rendering
+
+`displayMode === 'DISPLAY_ONLY'`: renders simple read-only cards (no radio/checkbox inputs). Uses `readOnlyList` as the data source.
+
+## Visual Specifications
+
+| Property             | Editable card                                    | Display-only card |
+| -------------------- | ------------------------------------------------ | ----------------- |
+| Cursor               | `pointer` (unless disabled/readOnly → `default`) | Default           |
+| Height               | `100%` (fills grid row)                          | Auto              |
+| Layout               | Column flex                                      | Row flex          |
+| Padding top          | 15px wrapper                                     | —                 |
+| Image (display-only) | 100px fixed width                                | 100px fixed width |
+| Card border          | Default (design-system card elevation)           | Default           |
+| Disabled             | `cursor: default`                                | —                 |
+
+**Visual-only styling notes:** Each card has a thin light border, small border radius, comfortable padding, a pointer cursor, and a column flex layout that fills the height of its grid row, with a small top margin; on hover the border switches to an accent color. Disabled cards use a default cursor and reduced opacity; read-only cards use a default cursor. The card label text uses the standard body font size and regular weight.
+
+## Edge Cases & Special Logic
+
+- **`resolveReferenceFields(item, hideFieldLabels, recordKey, pConn)`** — resolves additional display fields using the PConnect presets pattern. Gets field definitions from `pConnect.getRawMetadata().config.presets[0].children[0].children` (max 5 fields). For each preset, creates a PConnect instance via `PCore.createPConnect({ meta: { ...preset, config: { ...preset.config, displayMode: 'DISPLAY_ONLY', contextName: pConnect.getContextName() } }, useCustomContext: item })`, retrieves its metadata, and passes it to `prepareComponentInCaseSummary` to produce a rendered field component. The returned `value` for each field is a live rendered component (with proper formatting for currency, dates, etc.), NOT a plain string — render it directly in the UI.
+- **`prepareComponentInCaseSummary(pConnectMeta, getPConnect)`** — creates a display-only field component. Resolves the label from config, calls `getPConnect().createComponent({ type, children, config })`, then sets inherited props `displayMode: 'DISPLAY_ONLY'` and `readOnly: true` on the created component. Returns `{ name, value }`.
+- **Do NOT use `Object.keys(item)` to enumerate fields** — this shows raw internal keys, system properties, and unformatted values. Always use the presets-based resolution described above.
+- Checkbox `id={item[recordKey]}` — required for the card click handler to find and click the input by ID.
+- `getPConnect` input on the checkbox control: passed through to support SDK checkbox augmentation.
+- `imageDescriptionKey = showImageDescription ? imageDescription : undefined` — only show alt text when `showImageDescription` is true.
+- **`imageField`** — this value is the last path segment of the image property reference (e.g., if the Pega property path is `.PhoneImage`, the `imageField` passed to this component is `PhoneImage`). The parent component (RadioButtons or Checkbox) is responsible for extracting this segment before passing it.
+
+## Dependencies
+
+- Two local helper functions: `prepareComponentInCaseSummary` (creates display-only field components from metadata) and `resolveReferenceFields` (resolves preset fields into rendered components via `PCore.createPConnect`).
+- `PCore.createPConnect` — SDK API for creating PConnect instances from field metadata with custom context.
+- The DS's radio and checkbox components.
+- The DS's card/container component.
+- The DS's text/typography component.
+
+## Design System Mapping
+
+**UI control type:** Selectable card grid (radio or multi-select).
+
+When implementing in a specific design system, map the following:
+
+- **Card container** → use the DS's card component with a pointer cursor and click handler
+- **Radio/Checkbox** → use the DS's radio or checkbox component inside each card
+- **Card label** → use the DS's text/typography component for the card title
+- **Image layout** → configure flex direction based on `imagePosition` (inline-start, inline-end, or block)
+- **Read-only/display mode** → render simple cards without radio/checkbox inputs, using `readOnlyList` as data source
+- **"No Value" guard** → render plain text when no items are selected in read-only mode

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

@@ -2,21 +2,21 @@
 
 Clickable hyperlink that navigates to a referenced Pega case or data object using semantic URL resolution.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
 ## Component Purpose
 
-Renders a clickable link (`<a>` or button-style link) that navigates to a Pega case or data object. Resolves the correct semantic URL based on whether the reference is a Case or Data type. Handles Ctrl/Meta+click for opening in a new tab. Shows `'--'` when no text is provided.
+Renders a clickable link that navigates to a Pega case or data object. Resolves the correct semantic URL based on whether the reference is a Case or Data type. Handles Ctrl/Meta+click for opening in a new tab. Shows `'--'` when no text is provided.
 
 ## Pega Metadata
 
 - **Pega Name:** `SemanticLink`
 - **Type / Subtype:** `Field` / `Link-SemanticLink`
-- **Registration key:** `SemanticLink` (in `component-map.ts`)
+- **Registration key:** `SemanticLink` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
 | Prop                      | Type              | Default | Description                                                                        |
 | ------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------- |
@@ -30,6 +30,22 @@ 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`                                                        |
 
+## Implementation Structure
+
+This component computes a URL and renders a clickable link. Most logic is URL resolution — no form state.
+
+**Module Setup:** The component depends on a local utility module (`semanticUtils`) for data reference resolution. Define the input contract as an extension of the project's field input contract, adding `text`, `resourcePayload`, `resourceParams`, `previewKey`, `onClick`, `testId`, `referenceType`, `dataRelationshipContext`, and `contextPage` fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Receive inputs** (note: `onClick` is received but NOT used directly) — `text`, `resourcePayload` (default `{}`), `resourceParams` (default `{}`), `getPConnect`, `previewKey`, `onClick`, `testId` (default `''`), `referenceType`, `dataRelationshipContext` (default `null`), `contextPage`, and collect remaining inputs into `restInputs`.
+2. **Constants** — `ACTION_OPENWORKBYHANDLE` and `ACTION_SHOWDATA` from `PCore.getSemanticUrlUtils().getActions()`; `pConnect` via `getPConnect()`; `DATA` from `PCore.getConstants().RESOURCE_TYPES`, plus `WORKCLASS` and `CASE_INFO_CLASSID` from the same constants object.
+3. **URL resolution variables** — `linkURL` (default `''`), `payload` (default `{}`), `dataViewName`, and `isData` (default `false`).
+4. **Determine reference type and resolve the URL** — see the Behavioral Contract "URL Resolution" section.
+5. **`showDataAction()`** — calls `getPConnect().getActionsApi().showData(...)`; see the Behavioral Contract section below.
+6. **`openLinkClick(e)`** (click handler) — when neither `metaKey` nor `ctrlKey` is pressed, prevent the default navigation and instead call `showDataAction()` or `openWorkByHandle`; when either modifier key is pressed, let the browser open the `href` in a new tab.
+7. **Render the link** — a link element with `href` set to `linkURL`, the click handler, a test-id attribute, the remaining inputs spread, and content set to `text || '--'`.
+
 ## Behavioral Contract
 
 ### URL Resolution
@@ -41,14 +57,7 @@ Renders a clickable link (`<a>` or button-style link) that navigates to a Pega c
 - If `contextPage?.classID`: override `resourcePayload.caseClassName = contextPage.classID`
 - If `resourcePayload.caseClassName === WORKCLASS`: override with actual case class from `pConnect.getValue(CASE_INFO_CLASSID)`
 
-**Step 2a: Data reference (`referenceType === 'DATA'` or `shouldTreatAsDataReference`):**
-
-```
-const dataRefContext = semanticUtils.getDataReferenceInfo(pConnect, dataRelationshipContext, contextPage)
-dataViewName = dataRefContext.dataContext
-payload = dataRefContext.dataContextParameters
-isData = true
-```
+**Step 2a: Data reference (`referenceType === 'DATA'` or `shouldTreatAsDataReference`):** call `semanticUtils.getDataReferenceInfo(pConnect, dataRelationshipContext, contextPage)` to get a `dataRefContext`; set `dataViewName = dataRefContext.dataContext`, `payload = dataRefContext.dataContextParameters`, and `isData = true`.
 
 **Step 2b: Resource type DATA (`resourcePayload.resourceType === 'DATA'`):**
 
@@ -64,19 +73,7 @@ isData = true
 
 ### Click Handler (`openLinkClick`)
 
-```typescript
-function openLinkClick(e) {
-  if (!e.metaKey && !e.ctrlKey) {
-    e.preventDefault()
-    if (isData or shouldTreatAsDataReference) {
-      showDataAction()
-    } else if (previewKey) {
-      getPConnect().getActionsApi().openWorkByHandle(previewKey, resourcePayload.caseClassName)
-    }
-  }
-  // If metaKey/ctrlKey: allow default browser behavior (open in new tab)
-}
-```
+When neither `e.metaKey` nor `e.ctrlKey` is set: call `e.preventDefault()`, then either call `showDataAction()` (when this is a data reference or `shouldTreatAsDataReference` is true) or, when `previewKey` is set, call `getPConnect().getActionsApi().openWorkByHandle(previewKey, resourcePayload.caseClassName)`. When `e.metaKey` or `e.ctrlKey` is set, do nothing and allow the browser's default behavior (opening the link in a new tab).
 
 ### `showDataAction()`
 
@@ -89,7 +86,7 @@ No explicit `displayMode` handling — `SemanticLink` is always rendered as a li
 
 ## Visual Specifications
 
-Derived from `makeStyles` and MUI `Link` props:
+Derived from the reference component's styling:
 
 | Property    | Value                                    |
 | ----------- | ---------------------------------------- |
@@ -100,56 +97,37 @@ Derived from `makeStyles` and MUI `Link` props:
 | Font weight | 400                                      |
 | Underline   | Default link underline on hover          |
 | Cursor      | Pointer                                  |
-| Text        | `text` prop value, or `'--'` if empty    |
-
-**CSS-only implementation:**
-
-```css
-.semantic-link {
-  display: inline-block;
-  padding: 8px;
-  margin: 8px;
-  color: #1976d2;
-  text-decoration: none;
-  cursor: pointer;
-  font-weight: 400;
-  background: none;
-  border: none;
-  font-size: inherit;
-}
-.semantic-link:hover {
-  text-decoration: underline;
-}
-```
+| Text        | `text` input value, or `'--'` if empty   |
+
+**Visual-only styling notes:** The link renders as an inline block with 8px padding and margin on all sides, using the theme's primary link color with no default text decoration, a pointer cursor, normal font weight (400), transparent background, and no border, inheriting the surrounding font size; on hover the text becomes underlined.
 
 ## Edge Cases & Special Logic
 
 - **BUG-678282 fix:** When `resourceParams.workID === ''` and `previewKey` is a string, set `resourceParams.objectID = previewKey.split(' ')[1]` to handle cases where workID was not populated.
 - If `previewKey` is set: also set `resourceParams.id = previewKey`.
 - `linkURL` is computed synchronously at render — if an error occurs in data reference resolution, it is silently caught (`try/catch`) and `linkURL` remains `''`.
-- `onClick` prop from parent is received but NOT used directly — the component has its own `openLinkClick`. Do not call the parent's `onClick` directly.
+- `onClick` input from parent is received but NOT used directly — the component has its own `openLinkClick`. Do not call the parent's `onClick` directly.
 - **Ctrl/Meta+click**: `e.metaKey || e.ctrlKey` → don't `preventDefault()`, let the browser open the href in a new tab.
 - `text || '--'` is always rendered — never renders empty.
 
 ## Dependencies
 
-- `semanticUtils.getDataReferenceInfo(pConnect, dataRelationshipContext, contextPage)` from `./utils` (local).
+- Local utility: `semanticUtils.getDataReferenceInfo(pConnect, dataRelationshipContext, contextPage)`.
 - `PCore.getSemanticUrlUtils().getResolvedSemanticURL()` — URL resolution.
 - `PCore.getSemanticUrlUtils().getActions()` — `ACTION_OPENWORKBYHANDLE`, `ACTION_SHOWDATA`.
 - `PCore.getDataTypeUtils().getLookUpDataPage()`, `getLookUpDataPageInfo()`, `getDataPageKeys()`.
 - `PCore.getAnnotationUtils().isProperty()`, `getPropertyName()`.
 - `PCore.getConstants()` — `RESOURCE_TYPES.DATA`, `WORKCLASS`, `CASE_INFO.CASE_INFO_CLASSID`.
-- A link/anchor component (e.g., MUI `<Link component='button'>`, or native `<a>`/`<button>`).
+- A link/anchor element (native `<a>` with button-like behavior, or the DS's link component).
 
 ## Design System Mapping
 
 **UI control type:** Clickable hyperlink (button or anchor with navigation behavior).
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                |
-| ------------------ | ---------------------------------------------------- |
-| Default (CSS only) | `<button class="semantic-link">` with anchor styling |
-| MUI                | `<Link component='button'>`                          |
-| Ant Design         | `<Typography.Link>` or `<Button type="link">`        |
-| Chakra UI          | `<Link as="button">`                                 |
+- **Link element** → use the DS's link or button-link component (renders as an anchor with `href`)
+- **Click handler** → prevent default for normal clicks; allow Ctrl/Meta+click to open in new tab
+- **Empty text** → render `'--'` when `text` is falsy
+- **Padding/margin** → `8px` all sides
+- **Color** → primary link color from the theme

package/templates/react-sdk-reference/.ai-common/skills/field-skills/TextArea.md

@@ -0,0 +1,109 @@
+# Skill: TextArea
+
+Multi-line text input field that binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
+
+---
+
+## Component Purpose
+
+Renders an editable multi-line text area. Used for long-form text input such as descriptions, notes, or comments. Similar to `TextInput` but allows multiple lines with configurable min/max rows.
+
+## Pega Metadata
+
+- **Pega Name:** `TextArea`
+- **Type / Subtype:** `Field` / `Text` (multi-line)
+- **Registration key:** `TextArea` (in the project's component map)
+
+## Inputs (component-specific)
+
+| Name            | Type             | Description                                                |
+| --------------- | ---------------- | ---------------------------------------------------------- |
+| `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the textarea |
+
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Similar to TextInput but multiline with fixed rows. Does NOT delegate to TextInput in read-only mode.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`) and the project's event-commit utility (for committing value changes to the store). Define the input contract as an extension of the project's field input contract, adding an optional `fieldMetadata` field.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `testId`, `fieldMetadata`, `helperText`, `displayMode`, `hideLabel`, `placeholder`. Compute `helperTextToDisplay = validatemessage || helperText`, set up the PConnect instance, actions API, and bound property name, and derive `maxLength = fieldMetadata?.maxLength`.
+3. **Local state** — `inputValue` initialized to `''`; declare a read-only configuration object.
+4. **Sync from store** — a lifecycle effect watching `value` updates `inputValue` whenever it changes.
+5. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the raw `value`, the latter with a stacked variant.
+6. **Read-only** — set the read-only configuration to mark the textarea read-only when `readOnly` is true. Unlike TextInput, do NOT delegate to `TextInput` — preserve the multiline rendering even when read-only.
+7. **Test ID and handlers** — build a test-id attribute from `testId`; the change handler updates `inputValue` from the event's textarea value; the blur handler commits the value via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+8. **Render** — a multiline text input configured with: multiline mode enabled, minimum rows `5`, maximum rows `5`, full width, an outlined style when editable or flat/borderless style when read-only, small size, current `inputValue`, the change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, and `maxLength` plus the read-only/test-id attributes applied to the underlying textarea element.
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `''`.
+2. **Sync from store:** A lifecycle effect watching the `value` input updates `inputValue` whenever `value` changes.
+3. **On change:** Update local `inputValue` state only (do NOT commit to store on every keystroke).
+4. **On blur:** Commit to store via the project's event-commit utility with event type `'changeNblur'`, the property name, and `inputValue`.
+5. **Read-only:** Set the read-only attribute on the textarea; use a visually flat/borderless style. Omit the blur handler when read-only.
+6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the textarea's `maxLength` attribute.
+7. **Row sizing:** Fixed at minimum rows `5` and maximum rows `5` — the textarea does not auto-expand; it shows a scrollbar if content exceeds 5 rows.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the raw `value`.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
+- Both modes short-circuit before interactive rendering.
+
+## Read-Only Rendering
+
+Set the read-only attribute on the textarea element (NOT a read-only version via `TextInput` — preserves the multiline appearance). Switch to a flat/borderless visual style. The min/max rows constraint is still applied in read-only.
+
+## Visual Specifications
+
+Derived from the reference component's styling:
+
+| Property      | Standard (editable)                      | Read-only         |
+| ------------- | ---------------------------------------- | ----------------- |
+| Width         | 100%                                     | 100%              |
+| Min rows      | 5                                        | 5                 |
+| Max rows      | 5 (scrollable beyond)                    | 5                 |
+| Border        | 1px solid (outlined)                     | None (flat style) |
+| Border radius | 4px                                      | —                 |
+| Label         | Floating label                           | Floating label    |
+| Helper text   | Below textarea                           | Below textarea    |
+| Error state   | Red border + red helper text             | —                 |
+| Resize        | Vertical resize handle (browser default) | Same              |
+| Font size     | 0.875rem                                 | 0.875rem          |
+| Padding       | 8px 14px                                 | —                 |
+
+**CSS-only implementation notes:**
+
+- `textarea { min-height: calc(5 * 1.4375em + 16px); max-height: calc(5 * 1.4375em + 16px); overflow-y: auto; resize: vertical; }`
+- Error: `border-color: #d32f2f`
+- Read-only: `border: none; background: transparent;`
+
+## Edge Cases & Special Logic
+
+- Unlike `TextInput`, do NOT delegate to `TextInput` in read-only mode — render the textarea directly with the read-only attribute set, so the multi-line appearance is preserved.
+- `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
+
+## Dependencies
+
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
+- No third-party UI libraries required.
+
+## Design System Mapping
+
+**UI control type:** Multi-line text input (textarea).
+
+When implementing in a specific design system, map the following:
+
+- **Multiline input** → use the DS's textarea or multi-line text field component
+- **Row sizing** → configure minimum and maximum rows to `5`
+- **Read-only mode** → set the read-only attribute directly on the textarea (do NOT delegate to TextInput)
+- **Error state** → the DS's error/danger visual state
+- **maxLength** → pass to the textarea's `maxLength` attribute

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

@@ -2,38 +2,41 @@
 
 Static text display component that renders formatted text content (paragraph or heading). Non-interactive — no form binding.
 
-> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, display modes, event handling, and registration patterns common to ALL field components.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
 ## Component Purpose
 
-Displays static, read-only text content. Used to embed headings or descriptive paragraph text within forms or views. Not an input field — does NOT bind to a case property value and does NOT use `PConnFieldProps`. It renders purely based on static configuration props.
+Displays static, read-only text content. Used to embed headings or descriptive paragraph text within forms or views. Not an input field — does NOT bind to a case property value and does NOT use the project's field input contract. It renders purely based on static configuration inputs.
 
 ## Pega Metadata
 
 - **Pega Name:** `TextContent`
 - **Type / Subtype:** `Field` / `Text`
-- **Registration key:** `TextContent` (in `component-map.ts`)
+- **Registration key:** `TextContent` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-Extends `PConnProps` (NOT `PConnFieldProps` — there is no form value binding):
+The input contract extends the project's base component interface (NOT the field input contract — there is no form value binding), adding two required fields: `content` and `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';
-}
-```
-
-| Prop        | Type                                                                      | Description                                       |
+| Name        | Type                                                                      | Description                                       |
 | ----------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
 | `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 |
 
+## Implementation Structure
+
+Simplest possible component — no state, no lifecycle effects, just a switch on `displayAs`.
+
+**Module Setup:** Define the input contract as an extension of the project's base component interface (not the field input contract) with `content: string` and the `displayAs` union type.
+
+**Main Component Logic:**
+
+1. Receive `content` and `displayAs` from inputs.
+2. Switch on `displayAs` and render the matching element wrapping `content`: `'Paragraph'` → `<p>`, `'Heading 1'` → `<h1>`, `'Heading 2'` → `<h2>`, `'Heading 3'` → `<h3>`, `'Heading 4'` → `<h4>`.
+3. For any unrecognized `displayAs` value, log an error describing the unexpected value, then fall back to rendering `content` in a `<p>`.
+
 ## Behavioral Contract
 
 1. **No state, no effects** — purely presentational. Render `content` using the appropriate typography element for `displayAs`.
@@ -47,7 +50,7 @@ interface TextContentProps extends PConnProps {
 
 ## Display Mode Rendering
 
-Not applicable — this component is display-only by nature. It does not accept a `displayMode` prop.
+Not applicable — this component is display-only by nature. It does not accept a `displayMode` input.
 
 ## Read-Only Rendering
 
@@ -65,53 +68,25 @@ Derived from standard HTML typography:
 | `Heading 3` | `<h3>`          | 1.75rem     | 400         |
 | `Heading 4` | `<h4>`          | 1.5rem      | 400         |
 
-Color inherits from the surrounding text color. No padding, margin, border, or background beyond what the browser/design-system applies to the heading element.
-
-**CSS-only implementation notes:**
-
-```css
-.text-content-h1 {
-  font-size: 2.5rem;
-  font-weight: 300;
-}
-.text-content-h2 {
-  font-size: 2rem;
-  font-weight: 300;
-}
-.text-content-h3 {
-  font-size: 1.75rem;
-  font-weight: 400;
-}
-.text-content-h4 {
-  font-size: 1.5rem;
-  font-weight: 400;
-}
-.text-content-body {
-  font-size: 1rem;
-  font-weight: 400;
-}
-```
+Color inherits from the surrounding text color. No padding, margin, border, or background beyond what the browser/design-system applies to the heading element. Each heading level (and the paragraph/body style) uses only `font-size` and `font-weight` to differentiate visual hierarchy, per the table above — no other styling is applied.
 
 ## Edge Cases & Special Logic
 
-- Unrecognized `displayAs` values should trigger a `console.error` and fall back to body text.
-- No `handleEvent`, no store interaction, no `useEffect`.
+- Unrecognized `displayAs` values should trigger an error log and fall back to body text.
+- No event-commit utility, no store interaction, no lifecycle effects.
 
 ## Dependencies
 
 - No event utilities needed
 - No `FieldValueList` needed
-- Only a typography rendering element
+- Only a typography rendering element (native HTML or the DS's typography component)
 
 ## Design System Mapping
 
 **UI control type:** Static typography / text block.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                          |
-| ------------------ | -------------------------------------------------------------- |
-| Default (CSS only) | Native `<h1>`–`<h4>` or `<p>`                                  |
-| MUI                | `<Typography variant='h1' \| 'h2' \| 'h3' \| 'h4' \| 'body1'>` |
-| Ant Design         | `<Typography.Title level={1-4}>` or `<Typography.Text>`        |
-| Chakra UI          | `<Heading as='h1'-'h4'>` or `<Text>`                           |
+- **Paragraph** → use the DS's body text component or a `<p>` element
+- **Heading 1–4** → use the DS's heading component at the matching level, or native `<h1>`–`<h4>` elements
+- **No interaction** → this component has no event handling, state, or store binding