@pega/sdk 0.0.2 → 0.0.4

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

@@ -0,0 +1,231 @@
+# Skill: SelectableCard
+
+Card-style radio or checkbox selection grid with optional image support.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, 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 `component-map.ts`)
+
+> This component does NOT have a `config-ext.json` and does NOT extend `PConnFieldProps` — it's a design system component used internally by `RadioButtons` and `Checkbox`.
+
+## Props
+
+| 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                  |
+
+## Behavioral Contract
+
+### Data source selection
+
+```
+cardDataSource = (readOnly || displayMode === 'DISPLAY_ONLY')
+  ? readOnlyList || []
+  : 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):
+
+```typescript
+const handleCardClick = (event) => {
+  if (disabled || readOnly) return;
+  if (event.target.closest('label, input')) return; // native click already handled
+  const input = event.currentTarget.querySelector('input[type="radio"], input[type="checkbox"]');
+  if (input) input.click();
+};
+```
+
+### Subsection: Display mode (`displayMode === 'DISPLAY_ONLY'`)
+
+Render a **simple read-only card** (no radio/checkbox) with:
+
+- Optional image (`<img>`)
+- Card title: `item[cardLabel]`
+- Additional resolved fields (from `resolveReferenceFields`)
+- `style: { display: 'flex' }`
+
+```html
+<Card style="display: flex">
+  {image && <img src="..." alt="..." style="width: 100px" />}
+  <CardContent>
+    <body1>{item[cardLabel]}</body1>
+    {fields.map(field => <body2>{field.value}</body2>)}
+  </CardContent>
+</Card>
+```
+
+### Subsection: Editable mode (radio or checkbox)
+
+Render a **selectable card** with click handler, containing the appropriate input:
+
+```html
+<div style="paddingTop: 15px">
+  <Card style="cursor: pointer, height: 100%, flexDirection: column"
+        onClick={handleCardClick}>
+    <CardContent style={imageLayoutStyle}>
+      <!-- Image section (40% width for inline positions) -->
+      {image && <img full-width, aspect-ratio 16/9, contain>}
+      <!-- Content section (60% width for inline positions) -->
+      {type === 'radio'
+        ? <FormControlLabel control={<Radio value={item[recordKey]} checked={radioBtnValue === item[recordKey]} onChange={onChange} ... />} label={item[cardLabel]}>
+        : <FormControlLabel control={<Checkbox id={item[recordKey]} checked={readOnlyList.some(d => d[recordKey] === item[recordKey])} onChange={onChange} ... />} label={item[cardLabel]}>
+      }
+      {fields.map(field => <div style={fieldLayoutStyle}>{field.name && <div>{field.name}</div>}<div>{field.value}</div></div>)}
+    </CardContent>
+  </Card>
+</div>
+```
+
+### 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
+
+```css
+img {
+  width: 100%;
+  background-color: transparent;
+  aspect-ratio: 16 / 9;
+  max-height: 100%;
+  height: 100%;
+  object-fit: contain;
+  max-width: 100%;
+}
+```
+
+### Field display layout
+
+Each additional field in editable mode:
+
+```css
+.card-field {
+  font-size: 0.875rem;
+  display: grid; /* only if type !== 'TextArea' */
+  grid-template-columns: 1fr 1fr;
+  margin: 5px;
+}
+```
+
+### Radio tracking
+
+After iterating cards, if `type === 'radio'` and `setIsRadioCardSelected`:
+
+```
+if (radioBtnValue === item[recordKey]) radioItemSelected = true
+// After loop:
+setIsRadioCardSelected(radioItemSelected)
+```
+
+## 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`                                | —                 |
+
+**CSS-only card implementation:**
+
+```css
+.selectable-card {
+  border: 1px solid rgba(0, 0, 0, 0.12);
+  border-radius: 4px;
+  padding: 16px;
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  margin-top: 15px;
+  transition: border-color 0.2s;
+}
+.selectable-card:hover {
+  border-color: #1976d2;
+}
+.selectable-card.disabled {
+  cursor: default;
+  opacity: 0.7;
+}
+.selectable-card.readonly {
+  cursor: default;
+}
+.selectable-card-label {
+  font-size: 1rem;
+  font-weight: 400;
+}
+```
+
+## Edge Cases & Special Logic
+
+- **`resolveReferenceFields(item, hideFieldLabels, recordKey, pConn)`** — local utility that resolves additional display fields from an item record.
+- Checkbox `id={item[recordKey]}` — required for the card click handler to find and click the input by ID.
+- `getPConnect` prop on Checkbox (MUI): passed through to support `@pega/sdk-react` checkbox augmentation (non-standard MUI prop).
+- `imageDescriptionKey = showImageDescription ? imageDescription : undefined` — only show alt text when `showImageDescription` is true.
+
+## Dependencies
+
+- `resolveReferenceFields` from `./utils` (local utility).
+- Radio/Checkbox + FormControlLabel components.
+- Card/CardContent components.
+- Typography/text component.
+
+## Design System Mapping
+
+**UI control type:** Selectable card grid (radio or multi-select).
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                                                      |
+| ------------------ | -------------------------------------------------------------------------- |
+| Default (CSS only) | Custom `<div>` cards with `<input type="radio/checkbox">` inside           |
+| MUI                | `<Card>` + `<CardContent>` + `<FormControlLabel>` + `<Radio>`/`<Checkbox>` |
+| Ant Design         | Custom cards with `<Radio>`/`<Checkbox>`                                   |
+| Chakra UI          | `<Box>` as card + `<Radio>`/`<Checkbox>`                                   |

package/templates/react-sdk-reference/.claude/skills/field-skills/SemanticLink.md

@@ -0,0 +1,155 @@
+# Skill: SemanticLink
+
+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.
+
+---
+
+## 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.
+
+## Pega Metadata
+
+- **Pega Name:** `SemanticLink`
+- **Type / Subtype:** `Field` / `Link-SemanticLink`
+- **Registration key:** `SemanticLink` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop                      | Type              | Default | Description                                                                        |
+| ------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------- |
+| `text`                    | `string`          | —       | The visible link text; renders `'--'` if empty                                     |
+| `resourcePayload`         | `any`             | `{}`    | Resource payload containing `caseClassName`, `resourceType`, etc.                  |
+| `resourceParams`          | `any`             | `{}`    | Resource parameters containing `workID` for case navigation                        |
+| `previewKey`              | `string \| null`  | —       | Case preview key for opening work item by handle                                   |
+| `onClick`                 | `(event) => void` | —       | External click handler (received but not directly used — link has its own handler) |
+| `testId`                  | `string`          | `''`    | Test identifier                                                                    |
+| `referenceType`           | `string \| null`  | —       | `'DATA'` or case reference type                                                    |
+| `dataRelationshipContext` | `string \| null`  | `null`  | Context for data relationship resolution                                           |
+| `contextPage`             | `any`             | —       | Context page with `classID`                                                        |
+
+## Behavioral Contract
+
+### URL Resolution
+
+**Step 1: Determine if this is a data reference:**
+
+- `isData = false`
+- `shouldTreatAsDataReference = !previewKey && resourcePayload.caseClassName` (non-preview, has class)
+- 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 2b: Resource type DATA (`resourcePayload.resourceType === 'DATA'`):**
+
+- Look up data page: `dataViewName = PCore.getDataTypeUtils().getLookUpDataPage(resourcePayload.className)`
+- Look up page info and parameters
+- Build `payload` from parameters by resolving property annotations
+- `isData = true`
+
+**Step 3: Build `linkURL`:**
+
+- If `isData && dataViewName && payload`: `linkURL = PCore.getSemanticUrlUtils().getResolvedSemanticURL(ACTION_SHOWDATA, { pageName: 'pyDetails', dataViewName }, payload)`
+- Else (case): fix `resourceParams.objectID` for empty workID edge case, then `linkURL = PCore.getSemanticUrlUtils().getResolvedSemanticURL(ACTION_OPENWORKBYHANDLE, resourcePayload, resourceParams)`
+
+### 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)
+}
+```
+
+### `showDataAction()`
+
+- If `dataResourcePayLoad.resourceType === 'DATA'`: call `getPConnect().getActionsApi().showData('pyDetails', lookUpDataPage, payload)`
+- If `referenceType === DATA` or `shouldTreatAsDataReference`: call `showData('pyDetails', dataViewName, payload)`
+
+## Display Mode Rendering
+
+No explicit `displayMode` handling — `SemanticLink` is always rendered as a link. The parent (`ObjectReference`) controls whether to show it in display mode.
+
+## Visual Specifications
+
+Derived from `makeStyles` and MUI `Link` props:
+
+| Property    | Value                                    |
+| ----------- | ---------------------------------------- |
+| Display     | Inline link (button role)                |
+| Padding     | `8px` all sides                          |
+| Margin      | `8px` all sides                          |
+| Color       | Primary link color (blue, default theme) |
+| 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;
+}
+```
+
+## 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.
+- **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).
+- `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>`).
+
+## Design System Mapping
+
+**UI control type:** Clickable hyperlink (button or anchor with navigation behavior).
+
+Listed design systems are examples only.
+
+| 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">`                                 |

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

@@ -0,0 +1,98 @@
+# Skill: TextArea
+
+Multi-line text input field that binds to a Pega case property.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, props interface, 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 `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop            | Type             | Description                                                |
+| --------------- | ---------------- | ---------------------------------------------------------- |
+| `fieldMetadata` | `any` (optional) | Metadata object; used to read `maxLength` for the textarea |
+
+All other props come from `PConnFieldProps`. Import type as:
+
+```typescript
+import type { PConnFieldProps } from '@pega/sdk-react';
+```
+
+## Behavioral Contract
+
+1. **Local state:** Maintain `inputValue` in local state (string). Initialize to `''`.
+2. **Sync from store:** `useEffect` watching `value` prop — call `setInputValue(value)` 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 by calling `handleEvent(actions, 'changeNblur', propName, inputValue)`.
+5. **Read-only:** Set `readOnly` attribute on the textarea; use visually borderless ("standard") variant. Omit `onBlur` handler: `onBlur={!readOnly ? handleBlur : undefined}`.
+6. **maxLength:** Read from `fieldMetadata?.maxLength`; pass to the textarea's `maxLength` attribute.
+7. **Row sizing:** Fixed at `minRows={5}` and `maxRows={5}` — the textarea does not auto-expand; it shows a scrollbar if content exceeds 5 rows.
+
+## Display Mode Rendering
+
+- **`DISPLAY_ONLY`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} />`.
+- **`STACKED_LARGE_VAL`:** Render `<FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />`.
+- Both modes short-circuit before interactive rendering.
+
+## Read-Only Rendering
+
+Set `readOnly` on the textarea element (NOT a read-only version via `TextInput` — preserves the multiline appearance). Switch to a flat/borderless visual style. The `minRows`/`maxRows` constraint is still applied in read-only.
+
+## Visual Specifications
+
+Derived from the reference component's MUI props:
+
+| Property      | Standard (editable)                      | Read-only            |
+| ------------- | ---------------------------------------- | -------------------- |
+| Width         | 100%                                     | 100%                 |
+| Min rows      | 5                                        | 5                    |
+| Max rows      | 5 (scrollable beyond)                    | 5                    |
+| Border        | 1px solid (outlined)                     | None (standard/flat) |
+| 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 `readOnly` set, so the multi-line appearance is preserved.
+- `maxLength` is optional; only apply the attribute if `fieldMetadata?.maxLength` is defined.
+
+## Dependencies
+
+- `handleEvent` from `../../helpers/event-utils`
+- `getComponentFromRegistry('FieldValueList')` for display modes
+- No third-party UI libraries required
+
+## Design System Mapping
+
+**UI control type:** Multi-line text input (`<textarea>`).
+
+Listed design systems are examples only.
+
+| Design System      | Recommended Component                             |
+| ------------------ | ------------------------------------------------- |
+| Default (CSS only) | `<textarea rows="5">` with floating label         |
+| MUI                | `<TextField multiline minRows={5} maxRows={5} />` |
+| Ant Design         | `<Input.TextArea rows={5} />`                     |
+| Chakra UI          | `<Textarea />`                                    |
+| Shadcn/ui          | `<Textarea />`                                    |

package/templates/react-sdk-reference/.claude/skills/field-skills/TextContent.md

@@ -0,0 +1,117 @@
+# Skill: TextContent
+
+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.
+
+---
+
+## 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.
+
+## Pega Metadata
+
+- **Pega Name:** `TextContent`
+- **Type / Subtype:** `Field` / `Text`
+- **Registration key:** `TextContent` (in `component-map.ts`)
+
+## Props (component-specific)
+
+Extends `PConnProps` (NOT `PConnFieldProps` — there is no form value binding):
+
+```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                                       |
+| ----------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| `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 |
+
+## Behavioral Contract
+
+1. **No state, no effects** — purely presentational. Render `content` using the appropriate typography element for `displayAs`.
+2. **Mapping:**
+   - `'Paragraph'` → `<p>` / body text
+   - `'Heading 1'` → `<h1>`
+   - `'Heading 2'` → `<h2>`
+   - `'Heading 3'` → `<h3>`
+   - `'Heading 4'` → `<h4>`
+3. **Fallthrough:** Log an error for unrecognized `displayAs` values and render nothing (or a default fallback).
+
+## Display Mode Rendering
+
+Not applicable — this component is display-only by nature. It does not accept a `displayMode` prop.
+
+## Read-Only Rendering
+
+Always read-only — there is no editable state.
+
+## Visual Specifications
+
+Derived from standard HTML typography:
+
+| `displayAs` | Element         | Font size   | Font weight |
+| ----------- | --------------- | ----------- | ----------- |
+| `Paragraph` | `<p>` / `body1` | 1rem (16px) | 400         |
+| `Heading 1` | `<h1>`          | 2.5rem      | 300         |
+| `Heading 2` | `<h2>`          | 2rem        | 300         |
+| `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;
+}
+```
+
+## 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`.
+
+## Dependencies
+
+- No event utilities needed
+- No `FieldValueList` needed
+- Only a typography rendering element
+
+## Design System Mapping
+
+**UI control type:** Static typography / text block.
+
+Listed design systems are examples only.
+
+| 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>`                           |