@pega/sdk 0.0.2 → 0.0.3

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

@@ -0,0 +1,138 @@
+# Skill: RichText
+
+Rich text editor field with HTML content support, 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 a rich text (WYSIWYG) editor for HTML content. Uses a registry-resolved `RichTextEditor` component. Handles both read-only and editable states. Commits HTML content on blur by reading from the editor's internal ref.
+
+## Pega Metadata
+
+- **Pega Name:** `RichText`
+- **Type / Subtype:** `Field` / `Text-RichText`
+- **Registration key:** `RichText` (in `component-map.ts`)
+
+## Props (component-specific)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `additionalProps` | `object` (optional) | Extra props forwarded to the `RichTextEditor` |
+
+## Behavioral Contract
+
+1. **Editor ref:** Maintain an `editorRef` (via `useRef`) — the editor exposes its content via `editorRef.current.getContent({ format: 'html' })`.
+2. **No local state** — unlike text inputs, value is NOT tracked in local state. The editor manages its own internal content via `defaultValue`.
+3. **Props coercion:** `readOnly`, `required`, `disabled` must be coerced to booleans:
+   ```typescript
+   [readOnly, required, disabled] = [readOnly, required, disabled].map(
+     prop => prop === true || (typeof prop === 'string' && prop === 'true')
+   )
+   ```
+4. **Editable mode:**
+   - Track `status` for error state.
+   - **On change:** If `status === 'error'`, clear error messages via:
+     ```
+     pConn.clearErrorMessages({ property, category: '', context: '' })
+     ```
+   - **On blur:** Read HTML from editor ref and commit:
+     ```
+     const editorValue = editorRef.current.getContent({ format: 'html' })
+     handleEvent(actionsApi, 'changeNblur', property, editorValue)
+     ```
+5. **Read-only mode:** Render `RichTextEditor` with `readOnly` prop only — no `onChange`/`onBlur`.
+6. **`RichTextEditor` component:** Resolved via `getComponentFromRegistry('RichTextEditor')`. This is a design-system extension component that wraps the actual WYSIWYG library (e.g., TinyMCE).
+
+### Editable RichTextEditor props
+```
+label, labelHidden={hideLabel}, info={helperTextToDisplay}, defaultValue={value},
+placeholder, disabled, required, testId, ref={editorRef},
+error={status === 'error'}, onBlur={handleBlur}, onChange={handleChange}
+```
+
+### Read-only RichTextEditor props
+```
+label, labelHidden={hideLabel}, defaultValue={value}, testId, info={helperTextToDisplay},
+ref={editorRef}, readOnly
+```
+
+## Display Mode Rendering
+
+Display modes pass `isHtml={true}` to render HTML content safely:
+- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={value} isHtml />`
+- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={value} isHtml variant='stacked' />`
+
+## Read-Only Rendering
+
+Render `RichTextEditor` with `readOnly` prop. Uses same `editorRef`.
+
+## Visual Specifications
+
+The visual appearance of the rich text editor depends on the underlying `RichTextEditor` implementation. The reference implementation uses TinyMCE theming via CSS variables:
+
+```css
+/* RichText.css — must be imported */
+.tox .tox-toolbar { background-color: var(--app-background-color) !important; }
+.tox .tox-toolbar__primary { background-color: var(--app-background-color) !important; }
+.tox .tox-toolbar__button { color: var(--app-text-color) !important; }
+.tox .tox-toolbar__button--enabled {
+  background: var(--app-primary-color) !important;
+  color: #fff !important;
+}
+.tox .tox-dialog {
+  background-color: var(--modal-top-color) !important;
+  color: var(--app-text-color) !important;
+  border: 1px solid var(--modal-border-color) !important;
+  padding: 20px !important;
+  box-shadow: 0 0 10px 3px var(--modal-box-shadow-color) !important;
+}
+.tox .tox-dialog__header {
+  background-color: var(--modal-top-color) !important;
+  color: var(--app-text-color) !important;
+  font-weight: 500;
+  border-bottom: 1px solid var(--modal-border-color);
+}
+```
+
+**Note:** Import `./RichText.css` in the component file. The CSS variables (`--app-background-color`, `--app-text-color`, etc.) are set by the application theme.
+
+When implementing with a different design system:
+- Custom CSS for toolbar theming may be needed
+- The editor container should be full-width
+- Minimum height: ~200px for a usable editing area
+
+## Edge Cases & Special Logic
+
+- **Props coercion to boolean:** Pega may pass these props as strings (`'true'`/`'false'`) — always coerce.
+- **On blur, NOT on change:** Content is committed to the store only on blur (when user leaves the editor), not on every keystroke.
+- **Error clearing:** When `status === 'error'`, the `onChange` handler clears the error message from Pega so it doesn't persist after the user starts editing.
+- **`editorRef.current.getContent`:** This is specific to the TinyMCE API. For other rich text libraries, use the equivalent method to get HTML content.
+- **`FieldValueList` with `isHtml`:** The display mode renders HTML — ensure XSS protection in the `FieldValueList` component (use `dangerouslySetInnerHTML` only with sanitization, or a trusted HTML renderer).
+
+## Dependencies
+
+- `getComponentFromRegistry('RichTextEditor')` — the actual editor widget (e.g., TinyMCE wrapper).
+- `getComponentFromRegistry('FieldValueList')` for display modes.
+- `handleEvent` from `../../helpers/event-utils`.
+- `./RichText.css` — must be imported for TinyMCE toolbar theming.
+- `useRef` from React.
+
+**For other rich text editors:**
+- Any WYSIWYG editor that exposes `ref.current.getContent()` or equivalent.
+- Examples: Quill, Draft.js, Slate.js, CKEditor.
+
+## Design System Mapping
+
+**UI control type:** WYSIWYG rich text editor (HTML content).
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `contenteditable` div + custom toolbar OR TinyMCE |
+| MUI | `RichTextEditor` custom extension (TinyMCE) |
+| Ant Design | Quill or TinyMCE with Ant styling |
+| Chakra UI | Quill or TipTap with Chakra styling |

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

@@ -0,0 +1,124 @@
+# Skill: ScalarList
+
+Read-only display component that renders a list of scalar values by creating a child component for each item.
+
+> **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 list of scalar (primitive) values by dynamically creating a child component of a specified type for each item. Used for read-only display of list-type properties. Not an editable input.
+
+## Pega Metadata
+
+- **Pega Name:** `ScalarList`
+- **Type / Subtype:** `Field` / `ScalarList`
+- **Registration key:** `ScalarList` (in `component-map.ts`)
+
+## Props (component-specific)
+
+> ScalarList uses `PConnProps` (NOT `PConnFieldProps`) because its `value` is an array, not a string:
+
+```typescript
+import type { PConnProps } from '@pega/sdk-react';
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `any[]` | Array of scalar values to display |
+| `componentType` | `string` | The Pega component type to use for each item (e.g., `'TextInput'`, `'Date'`) |
+| `label` | `string` | Field label |
+| `displayMode` | `string` | Display mode |
+| `hideLabel` | `boolean` | Whether to hide the label |
+| `displayInModal` | `boolean` | Whether this is displayed in a modal context |
+
+All remaining props (`...restProps`) are forwarded to each child component.
+
+## Behavioral Contract
+
+1. **No state, no event handling** — purely display/read-only.
+2. **Item rendering:** Map each value in `scalarValues` to a component via `getPConnect().createComponent(...)`:
+   ```typescript
+   const items = scalarValues?.map(scalarValue =>
+     getPConnect().createComponent(
+       {
+         type: componentType,
+         config: {
+           value: scalarValue,
+           displayMode: 'DISPLAY_ONLY',
+           label,
+           ...restProps,
+           readOnly: 'true'
+         }
+       },
+       '',   // 2nd arg: empty string
+       '',   // 3rd arg: empty string
+       {}    // 4th arg: empty object
+     )
+   )
+   ```
+3. **`CommaSeparatedList` sub-component:** A local component that renders items as `<span>` elements inside a `<ul>` with no list styling:
+   ```html
+   <ul style="padding: 0; margin: 0;">
+     <span>item1</span>
+     <span>item2</span>
+     ...
+   </ul>
+   ```
+
+## Display Mode Rendering
+
+**`STACKED_LARGE_VAL` or `DISPLAY_ONLY`:**
+```html
+<div>
+  <CommaSeparatedList items={items} />
+</div>
+```
+No `FieldValueList` wrapper in these modes — the items are rendered directly.
+
+**Default (no display mode):**
+```
+<FieldValueList name={hideLabel ? '' : label} value={<CommaSeparatedList items={items} />} variant='stacked' />
+```
+
+## Visual Specifications
+
+| Property | Value |
+|----------|-------|
+| List style | No bullets, no padding, no margin on `<ul>` |
+| Item display | Each item rendered as `<span>` (inline) |
+| Separator | Items are adjacent spans (no comma separator despite the name) |
+| Layout | Vertical stack when wrapped in `FieldValueList variant='stacked'` |
+
+**CSS-only notes:**
+```css
+.scalar-list { list-style: none; padding: 0; margin: 0; }
+.scalar-list-item { display: inline; }
+```
+
+## Edge Cases & Special Logic
+
+- `scalarValues` may be `undefined` — the `?.map()` safely returns `undefined`; ensure null-check before rendering.
+- Each child component is created with `displayMode: 'DISPLAY_ONLY'` and `readOnly: 'true'` (as string) — the read-only is passed as a string, not boolean.
+- `restProps` includes all remaining props from the parent beyond the destructured ones — these are forwarded to each child component config.
+- `createComponent` takes 4 args — 2nd, 3rd, 4th are empty string/object as the typedef marks them optional.
+
+## Dependencies
+
+- `getComponentFromRegistry('FieldValueList')` for default display.
+- `getPConnect().createComponent()` — for creating each child component.
+- No `handleEvent` — read-only component.
+
+## Design System Mapping
+
+**UI control type:** Read-only list of scalar values.
+
+Listed design systems are examples only.
+
+| Design System | Recommended Component |
+|---|---|
+| Default (CSS only) | `<ul>` with `<span>` items |
+| MUI | `<List>` with `<ListItem>` or just `<Typography>` per item |
+| Ant Design | `<List>` items or `<Space>` with `<Tag>` |
+| Chakra UI | `<List>` or `<HStack>` with `<Tag>` |

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

@@ -0,0 +1,216 @@
+# 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,148 @@
+# 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">` |