@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 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.
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, and registration patterns common to ALL field components.
 
 ---
 
@@ -14,11 +14,11 @@ Renders a grid of selectable cards. Each card contains a radio button or checkbo
 
 - **Pega Name:** `SelectableCard`
 - **Type / Subtype:** Internal design system extension
-- **Registration key:** `SelectableCard` (in `component-map.ts`)
+- **Registration key:** `SelectableCard` (in the project's component map)
 
-> 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`.
+> 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`.
 
-## Props
+## Inputs
 
 | Prop                     | Type                    | Default | Description                                                                        |
 | ------------------------ | ----------------------- | ------- | ---------------------------------------------------------------------------------- |
@@ -44,70 +44,30 @@ 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)}
-    </>
-  );
-}
-```
+## 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 = (readOnly || displayMode === 'DISPLAY_ONLY')
-  ? readOnlyList || []
-  : dataSource?.source
-```
+`cardDataSource` is `readOnlyList` (or `[]` if empty) when `readOnly` or `displayMode === 'DISPLAY_ONLY'`; otherwise it is `dataSource?.source`.
 
 ### "No Value" guard
 
@@ -115,57 +75,15 @@ If `showNoValue`: render a plain text element showing `'No Value'` and return ea
 
 ### 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();
-};
-```
+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) 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>
-```
+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** 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>
-```
+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)
 
@@ -177,40 +95,15 @@ Render a **selectable card** with click handler, containing the appropriate inpu
 
 ### Image element
 
-```css
-img {
-  width: 100%;
-  background-color: transparent;
-  aspect-ratio: 16 / 9;
-  max-height: 100%;
-  height: 100%;
-  object-fit: contain;
-  max-width: 100%;
-}
-```
+**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
 
-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;
-}
-```
+**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
 
-After iterating cards, if `type === 'radio'` and `setIsRadioCardSelected`:
-
-```
-if (radioBtnValue === item[recordKey]) radioItemSelected = true
-// After loop:
-setIsRadioCardSelected(radioItemSelected)
-```
+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
 
@@ -228,59 +121,35 @@ setIsRadioCardSelected(radioItemSelected)
 | 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;
-}
-```
+**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)`** — local utility that resolves additional display fields from an item record.
+- **`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` prop on Checkbox (MUI): passed through to support `@pega/sdk-react` checkbox augmentation (non-standard MUI prop).
+- `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
 
-- `resolveReferenceFields` from `./utils` (local utility).
-- Radio/Checkbox + FormControlLabel components.
-- Card/CardContent components.
-- Typography/text component.
+- 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).
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| 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>`                                   |
+- **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/.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,69 +30,21 @@ 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
+## Implementation Structure
 
 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>
-  );
-}
-```
+**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
 
@@ -105,14 +57,7 @@ export default function SemanticLink(props: SemanticLinkProps) {
 - 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'`):**
 
@@ -128,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()`
 
@@ -153,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                                    |
 | ----------- | ---------------------------------------- |
@@ -164,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