@pega/sdk 0.0.13 → 0.0.15

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

@@ -0,0 +1,385 @@
+# Skill: EmbeddedData
+
+Single embedded record stored directly on the case, presented as a picker that copies a chosen record onto the case.
+
+> **Prerequisite skill:** [`field-components.md`](../field-components.md) — covers architecture, input contract, display modes, event handling, the shared Condition Encoding contract, and registration patterns common to ALL field components.
+
+> **Sibling skill:** [`EmbeddedDataMulti.md`](./EmbeddedDataMulti.md) — the same Pega field type configured to hold a **list** of records. It compiles to a different node type and a different component; see the Node Type Matrix below.
+
+---
+
+## Component Purpose
+
+Renders a single record that is **owned by the case** rather than referenced from elsewhere. An embedded record has no data page behind it: the record lives on the case's own page structure. That single fact separates this field type from every reference field, and it removes an entire category of configuration — there is no datasource rule, no parameters, and no search.
+
+The configuration surface offers only two choices about the data itself: whether the field holds one record or a list, and which class of record it holds. Everything else is presentation.
+
+A single record has **two** presentations, and they are not variants of one component — they are different node types:
+
+- An **inline form**, which is a plain view reference and needs no component at all.
+- A **picker**, which is this component. It offers a list of candidate records, and copies the chosen one onto the case.
+
+Read the Node Type Matrix before anything else. The presentation is decided by the node's own type, not by a configuration key alone.
+
+## Pega Metadata
+
+- **Pega Name:** `EmbeddedData`
+- **Type / Subtype:** `Field` / `EmbeddedData`
+- **Registration key:** `EmbeddedData` (in the project's component map)
+- **Shown in the configuration UI as:** `Embedded Data`, with a subtitle reading "single record" and naming the target class
+
+### Node Type Matrix
+
+One Pega field type compiles to three different node types. The type is **not** carried in a configuration key — it is the node's own type.
+
+| Options         | Display as                                       | Node type           | Component                                   |
+| --------------- | ------------------------------------------------ | ------------------- | ------------------------------------------- |
+| Single record   | `Form`                                           | `reference`         | none — the runtime's generic reference path |
+| Single record   | `Combo-box`                                      | `EmbeddedData`      | **this component**                          |
+| List of records | `Table`, `Repeating view`, and the read-only set | `EmbeddedDataMulti` | see the sibling skill                       |
+
+Three consequences follow, and all three are easy to get wrong:
+
+1. **Resolve the node type first, and only then a configuration key.** For a single record the node type already tells you which of two completely different presentations applies. Reading `displayAs` first leads to treating an inline form and a picker as variants of one component, which they are not.
+2. **The inline form needs no component at all.** It is a plain view reference, resolved by the same machinery that resolves any other view reference. Do not generate a component for it. Its contract is documented below because a generated project must still understand it — not because anything must be built for it.
+3. **A field type's presentation control does not always map to a configuration key.** Across Pega field types this mechanism varies — some carry the presentation in a `displayAs` key, some in a `componentType` key, and some change the node type itself. Embedded data does **both**: the node type changes _and_ a `displayAs` key is emitted. Never generalise one field type's mechanism to another.
+
+### Distinguishing an embedded record from a data reference
+
+A single embedded record in its inline-form presentation and a data reference field both arrive as a node of type `reference` whose configuration declares a view. They are **not** the same thing and must not be rendered the same way. Discriminate on these keys:
+
+| Key             | Embedded record (inline form)    | Data reference                         |
+| --------------- | -------------------------------- | -------------------------------------- |
+| `context`       | a bare property path on the case | a class name carrying the class marker |
+| `authorContext` | absent                           | present — the property path            |
+| `referenceType` | absent                           | present, naming the kind of reference  |
+| `displayAs`     | the inline-form value            | absent                                 |
+
+The reliable test is the pair: a `context` that is a property path, together with the inline-form `displayAs` value. Both must hold.
+
+This matters in practice because a single payload commonly contains both kinds side by side — an embedded record's view will itself contain data reference fields, each of which is a `reference` node of the second kind.
+
+### Configuration Surfaces
+
+There are **two** separate surfaces, with different lifetimes. Keep them distinct.
+
+**Surface 1 — the per-view field dialog.** Settings stored per view, reached from the field within a view. Its control set differs by presentation:
+
+| Presentation | Controls offered                                                                                          |
+| ------------ | --------------------------------------------------------------------------------------------------------- |
+| Inline form  | Display as, Label, Show label, View, Visibility                                                           |
+| Picker       | Display as, Label, Combo-box source, Display field, Show details, Required, Disabled, Visibility, Test ID |
+
+Note what the inline form does **not** offer: no Edit mode, no Required, no Disabled, no placeholder, no helper text, no Test ID. An inline form has no single scalar value, so most field-level settings are meaningless for it. For the same reason its Visibility control omits the "if not blank" and "if not zero" conveniences, which only exist where a scalar bound value can be tested.
+
+**Surface 2 — the field-definition screen.** Settings stored on the field definition, shared by every view that uses the field. It carries the record class and the single-versus-list choice, and nothing render-related for this presentation.
+
+### Config Keys — common to both presentations
+
+| Configuration control                      | Emitted config key(s)                             | Value shape and notes                                                                                                                                                                                                                                                                        |
+| ------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| (platform-emitted)                         | `ruleClass`                                       | The class of the embedded record. Read it verbatim; never derive or normalise a class name                                                                                                                                                                                                   |
+| Label                                      | `label` + `labelOption`                           | `labelOption` is the default value when the field's own name is kept, and the label is then **plain text with no marker**; it is the custom value when text is supplied, and the label then carries the localization marker. Always render the resolved label; never branch on `labelOption` |
+| Required / Disabled / Visibility / Test ID | `required` / `disabled` / `visibility` / `testId` | See the shared Condition Encoding contract; `testId` is a plain, non-localized string. The inline form emits only `visibility`                                                                                                                                                               |
+
+There is **no** `targetObjectType` key. Embedded data has no data-versus-case distinction, so any logic written for reference fields that branches on such a key does not apply.
+
+Equally, there is **no** `referenceList` and **no** `parameters`. A component that goes looking for a data page will find none. This is the single biggest structural difference from the reference fields, and the easiest thing to get wrong by pattern-matching against them.
+
+### Config Keys — inline form (no component required)
+
+The node carries only these:
+
+| Key              | Meaning                                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------------------- |
+| `type`           | Declares that this reference resolves to a view                                                          |
+| `name`           | The **rule name** of the chosen view. The picker displays a friendly label; the stored value is the name |
+| `ruleClass`      | The class the referenced view belongs to — the embedded record's class                                   |
+| `context`        | The path to the embedded page on the case. Emitted **bare**, with no property marker                     |
+| `displayAs`      | The inline-form value                                                                                    |
+| `inheritedProps` | A list of name/value pairs to be applied to the referenced view — see below                              |
+| `visibility`     | Present only when configured away from its default                                                       |
+
+**The `inheritedProps` contract.** This is the only place in the field type where settings travel in a list rather than as keys, and it is the single most common source of an unlabelled embedded form.
+
+- It carries presentation settings destined for the **referenced view**, not for the reference node. Two are observed: the field's label, and a flag controlling whether that label is shown. The flag is a **positive** show-label flag, not the hide-label flag used elsewhere.
+- Its entries must be **flattened onto the resolved view's configuration as ordinary keys**. Passing the list through unchanged, or looking for a top-level label on the reference node, both produce a form with no label.
+- There is **no** `labelOption` here.
+- Conditions such as visibility are **not** in this list. They stay on the reference node and govern whether the node renders at all. Never merge a condition into the referenced view.
+- The referenced view arrives in **two shapes** depending on when the payload was produced: sometimes with the inherited values already flattened onto it, and sometimes without. The merge must therefore be performed rather than assumed, and it must be safe to apply to a view that already has the values.
+
+The referenced view is delivered **eagerly**, as a sibling entry in the same payload keyed by its rule name. No fetch is required to resolve it.
+
+### Config Keys — picker
+
+| Key           | Meaning                                                                                                         |
+| ------------- | --------------------------------------------------------------------------------------------------------------- |
+| `displayAs`   | The combo-box value. Note the emitted spelling has no separator, unlike the label shown in the configuration UI |
+| `datasource`  | An **object**, not a string — see below                                                                         |
+| `targetPage`  | The path to the embedded page the selected record is copied into                                                |
+| `value`       | The bound display value: the target page path followed by the record's label property                           |
+| `editable`    | Boolean                                                                                                         |
+| `placeholder` | Prompt text, already resolved                                                                                   |
+| `ruleClass`   | The embedded record's class                                                                                     |
+| `children`    | One `reference` child naming a details view, present when the show-details setting is configured                |
+
+**The `datasource` object** has three parts: a source, a field map, and a copy-all flag.
+
+- The **source** carries a datasource marker followed by a property path — and that path points at **another embedded data field on the same case**, specifically a list-of-records one. A single embedded record in its picker presentation draws its options from an embedded list elsewhere on the same case. This is a genuine dependency between two field instances on one case; the options never come from anywhere external.
+- The **field map**'s key entry carries the configured display property — the property shown to identify each candidate record.
+- The **copy-all flag** indicates that the whole selected record is copied into the target page, rather than just an identifier being stored.
+
+**The details child.** When the show-details setting is configured, the node gains one child: a `reference` node naming a view that describes the referenced record in detail. It is delivered eagerly in the same payload and **must be rendered** — dropping it silently loses the configured detail presentation.
+
+**Explicit defaults.** This presentation emits `required` and `visibility` explicitly even when both are at their defaults, while the inline form omits them at identical settings. Another reason never to read intent from key presence.
+
+### Raw and Resolved Configuration
+
+The runtime hands the component its inputs after replacing every marker with its current value, and a property-reference marker becomes _the current value of that property_. That is right for text and conditions, and wrong for anything that names a property or a source.
+
+- Read from the **resolved inputs**: `label`, `placeholder`, `required`, `disabled`, `visibility`, `readOnly`, `displayMode`, `hideLabel` and `testId`.
+- Read from the **raw configuration**, `getPConnect().getRawMetadata().config`: the `datasource` object with its `source` and `fields`, `targetPage`, `value`, `ruleClass` and `displayAs`. Take a copy and never modify the original.
+
+Strip a marker only where this skill says to derive a bare path, and prefer `PCore.getAnnotationUtils().getPropertyName(...)` to trimming it by hand.
+
+### Annotation Prefixes
+
+A **property reference** marker points at a property. A **localization** marker precedes user-facing text. A **locale reference** marker identifies the view's localization bundle. A **field label** marker resolves a property's configured label. A **user reference** marker identifies an operator-valued property. An **associated datasource** marker points at an associated list. A **field metadata** marker points at a field's own metadata. An **attachment** marker identifies an attachment-valued property. A **class context** marker names a class. A **datasource** marker names a source of rows. An **expression** marker precedes a computed condition. A **When Rule** marker names a decision rule.
+
+Three rules about markers, all of which were observed to break naive assumptions:
+
+**Marker use is level-dependent.** Keys consumed directly by this component are emitted bare — notably the embedded page path on the inline form. Keys inside nested nodes, which the runtime resolves as ordinary fields, do carry markers. Never normalise one rule across both levels, and never test for a marker to decide what a value means.
+
+**A marked value may be empty.** A localization or field-label marker followed by nothing at all is a real, observed value. Handle it as empty text rather than as the literal marker.
+
+**The same setting may be marked in one payload and plain in another.** A label has been observed both as already-resolved plain text and as a field-label marker pointing at the property, with the identical label option in both cases. Take the label from the resolved inputs and make no assumption about which shape produced it.
+
+Finally: wherever a configuration picker shows a friendly description — of a view, a decision rule, or a class — the stored value is the underlying **rule name**. The two are unrelated strings. Do not assume a naming convention either: within one payload, one view's stored name matched its displayed label exactly while another's did not.
+
+### Preview Metadata Hazards
+
+View metadata captured from the configuration UI is _preview_ metadata and substitutes placeholder values. Two consequences matter here, because tooling that discovers components by walking view metadata will read placeholders as real.
+
+**Placeholder property paths are named for a field type, not a field.** Two different fields of the same type therefore share one identical bound path, distinguished only by their labels. Never use a bound path as an identity, a key, or a de-duplication criterion.
+
+**A placeholder path is not even stable for one field.** The same property has been observed emitting different placeholder paths depending on how its presentation was configured, with extra deferred-loading keys appearing and disappearing alongside. Changing a configuration can therefore change a bound path without any property having changed.
+
+### Key Lifecycle Rules
+
+This field type clears keys inconsistently. Five distinct behaviours have been observed across the field type as a whole, and the same caution applies here:
+
+1. A control that disappears may leave its key behind carrying the old value.
+2. A control that disappears may instead have its key cleared.
+3. Both can happen in the same transition, with no way to predict which.
+4. A key cleared by one change may reappear later carrying a **re-seeded default** rather than the value last configured for it.
+5. Keys may be re-seeded even for controls that are not visible in the current mode.
+
+Switching between the inline form and the picker changes the node type, so most keys do not survive the transition — but the rule still holds: **decide which settings are active from the node type and `displayAs`, never from key presence, and never from a key's value.**
+
+### Generation Rules
+
+1. Establish the node type before anything else. This component handles only the picker node type.
+2. Do not generate a component for the inline form. Let the runtime's generic reference machinery resolve it.
+3. When consuming an inline-form node, flatten `inheritedProps` onto the resolved view's configuration, idempotently, and never look for those values as top-level keys on the reference node.
+4. Classify a `reference` node as an embedded record or a data reference before rendering it; they are different components.
+5. Never read a data page or parameters for this field type. The picker's options come from an embedded list on the same case, named by the `datasource` object's source entry.
+6. Copy the **whole** selected record into `targetPage`. The copy-all flag means a record, not an identifier.
+7. Render this component's children, so a configured details view appears.
+8. Apply mode precedence: while the field is read-only, ignore configured required, disabled and placeholder settings even when those keys are present.
+9. Implement the settings listed under Implementation Status rather than reproducing the gaps.
+10. Confirm every registry dependency exists before relying on it — see Registry Dependency Prerequisite.
+
+## Inputs (component-specific)
+
+> Extends the project's field input contract.
+
+For every input below, an absent value means the stated default. An empty string means the setting was never given a value and must be treated exactly like an absent one.
+
+### Picker — this component
+
+| Input         | Type                 | Default | Description                                                                         |
+| ------------- | -------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `getPConnect` | `any`                | —       | The PConnect accessor                                                               |
+| `displayAs`   | `string`             | —       | The combo-box value                                                                 |
+| `datasource`  | `object`             | —       | Source, field map, and copy-all flag — see Config Keys                              |
+| `targetPage`  | `string`             | —       | Path to the embedded page the selection is copied into                              |
+| `value`       | `string` (optional)  | `''`    | Bound display value                                                                 |
+| `editable`    | `boolean` (optional) | `false` |                                                                                     |
+| `placeholder` | `string` (optional)  | `''`    | Already resolved                                                                    |
+| `ruleClass`   | `string`             | —       | Class of the embedded record                                                        |
+| `label`       | `string` (optional)  | `''`    | Already resolved                                                                    |
+| `labelOption` | `string` (optional)  | default | Informational only                                                                  |
+| `required`    | `boolean` (optional) | `false` | Already-resolved boolean; may be emitted explicitly at its default                  |
+| `disabled`    | `boolean` (optional) | `false` | Already-resolved boolean                                                            |
+| `readOnly`    | `boolean` (optional) | `false` | Supplied by the surrounding view                                                    |
+| `visibility`  | `boolean` (optional) | `true`  | Already-resolved boolean; the component is normally not rendered at all when false  |
+| `hideLabel`   | `boolean` (optional) | `false` |                                                                                     |
+| `testId`      | `string` (optional)  | `''`    | Test identifier                                                                     |
+| `displayMode` | `string` (optional)  | —       | Supplied by the surrounding view; a display-only value forces a read-only rendering |
+| `children`    | `any` (optional)     | —       | A details-view reference, present when show-details is configured; MUST be rendered |
+
+### Inline form — the reference node, for reference only
+
+> No component is generated for this. The table documents what the runtime's reference machinery consumes.
+
+| Input            | Type                 | Default | Description                                                            |
+| ---------------- | -------------------- | ------- | ---------------------------------------------------------------------- |
+| `getPConnect`    | `any`                | —       | The PConnect accessor                                                  |
+| `type`           | `string`             | —       | Declares that the reference resolves to a view                         |
+| `name`           | `string`             | —       | Rule name of the referenced view                                       |
+| `ruleClass`      | `string`             | —       | Class of the referenced view                                           |
+| `context`        | `string`             | —       | Bare path to the embedded page on the case                             |
+| `displayAs`      | `string`             | —       | The inline-form value                                                  |
+| `inheritedProps` | `array` (optional)   | —       | Name/value pairs to flatten onto the resolved view                     |
+| `visibility`     | `boolean` (optional) | `true`  | Already-resolved boolean; the node is normally not rendered when false |
+
+## Implementation Structure
+
+An orchestrator. It resolves one presenting picker from the registry, derives a configuration for it, and renders it inside a single full-width container. It draws no control of its own.
+
+### Registry Dependency Prerequisite
+
+> **Check this before writing the component.** Because this component only orchestrates another, it cannot work unless its dependency is already generated and registered.
+
+Tooling that discovers components by walking a case's view metadata will not find the picker component, because it never appears there as a field — it is a building block reached for at runtime. A discovery-driven generation pass can therefore produce this component while silently omitting what it depends on, and a registry lookup that finds nothing degrades to a blank render rather than raising an error.
+
+The registry keys this component reaches for: the search/typeahead component (`AutoComplete`) or the dropdown/select component (`Dropdown`), whichever the project provides for a single-choice picker, and the value-display component (`FieldValueList`) for display-only rendering.
+
+The dependency is **transitive** through the details child: the view named by that child contains ordinary field nodes, and every type present in it is also a dependency. Enumerate the types actually present in your metadata and check those too.
+
+Before finishing: confirm each required key is registered or was generated earlier in the session; generate and register anything missing from its own skill file; only then wire up the lookups.
+
+**Module Setup:** The component depends on the project's component registry and on the platform APIs listed below. Define the input contract as an extension of the project's field input contract, adding every input in the picker table above.
+
+**Main Component Logic** — in order:
+
+1. **Registry lookup.** Resolve the presenting picker component. See the prerequisite above.
+2. **Receive inputs,** each defaulted as documented.
+3. **Resolve the option source.** Read the raw `datasource` object's source entry and strip its marker to obtain the path of the embedded list that supplies the candidate records.
+4. **Resolve the display property** from the raw `datasource` field map's key entry.
+5. **Apply mode precedence.** When the field is read-only or the surrounding view is display-only, render the resolved display value through the value-display component and stop.
+6. **Render the picker** with the option source, the display property, the placeholder, the label, and the resolved condition states.
+7. **Render this component's children** so that a configured details view appears.
+8. Wrap the result in a single full-width container.
+
+## Behavioral Contract
+
+### Selection and commit
+
+When the user selects a record, copy the **whole** selected record into the path named by `targetPage`. The copy-all flag on the `datasource` object is what specifies this: the field stores a copy of the record on the case, not a pointer to it. Writing only an identifier leaves the embedded page empty and every downstream field blank.
+
+The bound display value is the target page path followed by the record's label property, so once the copy is made the display value resolves without further work.
+
+### The details child
+
+The show-details setting produces one child node naming a view that describes the referenced record. It is delivered eagerly in the same payload. Render it — dropping it leaves the configured detail presentation missing with no error reported.
+
+### Inline form — what the runtime does
+
+Documented so that a generated project can reason about it, not so that anything is built for it.
+
+The reference node is resolved by looking up the view named by `name`. Each entry of `inheritedProps` is flattened onto that view's configuration as an ordinary key, giving the view a label and a show-label flag. The view is then rendered through its own template, which draws the embedded record's fields. Nothing contributes chrome of its own, and there is no `label` key on the reference node — looking for one yields an unlabelled form.
+
+### View references and loading
+
+| Mechanism                       | Referenced view delivered? | Resolution                |
+| ------------------------------- | -------------------------- | ------------------------- |
+| The inline form's view          | yes                        | eagerly, from the payload |
+| The picker's details-view child | yes                        | eagerly, from the payload |
+
+Both are present in the payload; neither requires a fetch.
+
+## Worked Traces
+
+Two walkthroughs. Each names the active keys and what is handed down.
+
+**Inline form.** The node type is `reference`, so this component is not involved at all. Active keys: `type`, `name`, `ruleClass`, `context`, `displayAs`, `inheritedProps`, and `visibility` if configured. Resolve the view named by `name` from the payload. Flatten each entry of `inheritedProps` onto that view's configuration as a flat key, so the view gains a label and a show-label flag. Render the view through its own template. Note there is no `label` key on the node — looking for one yields an unlabelled form. Note also that `context` is a bare property path, which is what distinguishes this node from a data reference.
+
+**Picker with a details view.** The node type is `EmbeddedData`. Active keys: `displayAs`, `datasource`, `targetPage`, `value`, `editable`, `placeholder`, `ruleClass`, the label pair, the three conditions, `testId`, and one child. Read the option source from the `datasource` object and strip its marker — it names another embedded list on the same case, not a data page. Read the display property from the field map. Render a picker over that list, showing the display property for each candidate. On selection, copy the whole record into `targetPage`. Render the child so the configured details view appears. Ignore anything resembling a data page name: there is none. Note that `required` and `visibility` may be present at their defaults — their presence says nothing about intent.
+
+## Display Mode Rendering
+
+Display mode reaches this component from the surrounding view and is not the same thing as the field's own read-only state. Either forces a read-only rendering, and both must be checked.
+
+In a display-only or read-only rendering, show the resolved display value through the project's value-display component rather than a disabled picker. Apply mode precedence at the same time: ignore configured required, disabled and placeholder settings, which may still be present as stale keys from when the field was last editable.
+
+## Visual Specifications
+
+This component contributes only a single full-width container holding one child. Everything visible is produced by the presenting component.
+
+| Property   | Value                                            |
+| ---------- | ------------------------------------------------ |
+| Container  | Full width, single column, no padding of its own |
+| Appearance | Entirely delegated to the presenting component   |
+
+## Edge Cases & Special Logic
+
+- **The node type, not a configuration key, chooses the presentation.** Reading `displayAs` first leads to the wrong component or none.
+- **A `reference` node may be an embedded record or a data reference.** Use the discriminator table; they render completely differently.
+- **`inheritedProps` is a list, and its values belong on the referenced view.** Passing it through unchanged produces an unlabelled form, and the merge must be idempotent because the view arrives in two shapes.
+- **There is no data page.** The picker's options come from an embedded list on the same case. Any logic that looks for a datasource rule or parameters is inapplicable.
+- **The option source is another field on the same case.** If that field is absent or empty, the picker has nothing to offer — report it rather than rendering an empty control with no explanation.
+- **Copying an identifier instead of the record leaves the page empty.** The copy-all flag means the whole record.
+- **Defaults may be emitted explicitly.** This presentation emits `required` and `visibility` at their defaults while the inline form omits them. Key presence never indicates intent.
+- **The details child must be rendered.** Dropping it loses the configured detail presentation silently.
+- **An empty marked string is a real value.** Treat it as empty text.
+- **A missing registry entry degrades silently.** An omitted dependency looks like a styling problem, not an error.
+
+## Implementation Status
+
+| Setting or presentation | Reference behaviour                                                                                  | What a generated component should do                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| The picker itself       | No component is registered under this key at all, so the field resolves to nothing and renders blank | Provide and register it, per the sections above         |
+| The details child       | Not rendered                                                                                         | Render the child so the configured details view appears |
+
+## Dependencies
+
+> Every registry dependency must be generated and registered before this component can render — see Registry Dependency Prerequisite.
+
+- The project's component registry, resolving the single-choice picker (`AutoComplete` or `Dropdown`, whichever the project provides), the value-display component (`FieldValueList`), and the type of every field present in the details view.
+- The Pega Platform APIs listed below.
+
+## Pega Platform APIs
+
+All of these are reached through the global `PCore` object, which the SDK runtime installs before any component renders. Never import them from a package — read them off `PCore` at the point of use.
+
+**`PCore.getAnnotationUtils().getPropertyName(value)`** — takes a marker-prefixed property path and returns the bare property name. Use it to turn the `datasource` object's source entry into the path of the embedded list, and wherever else a stored path must become a property name, instead of trimming a marker yourself.
+
+**`PCore.getMetadataUtils().resolveView(viewName)`** — takes a view name and returns that view's metadata, which may be a single view or a list of views for different classes. Used when a referenced view must be resolved by name rather than read from the payload; when a list is returned, select the entry whose class matches the embedded record's class.
+
+**`getPConnect().getValue(path)`** — reads the list of candidate records from the resolved option-source path, and reads the current display value.
+
+**`getPConnect().getActionsApi()`** — provides the operation that writes the selected record onto the case at `targetPage`.
+
+**`getPConnect().createComponent(...)`** — builds the presenting child from a derived configuration.
+
+**`getPConnect().getRawMetadata()`** — returns the component's configuration **before** markers are resolved. Required when a bound path is needed as a property name rather than as a resolved value.
+
+The context name, the page reference, and the change handler all come from the PConnect accessor rather than from `PCore`.
+
+## Design System Mapping
+
+**UI control type:** Embedded record picker — an orchestrator that delegates to a single-choice picker and copies the chosen record onto the case.
+
+When implementing in a specific design system, map the following:
+
+- **Picker presentation** → the design system's combobox, typeahead, or select, sourced from another embedded list on the same case and showing the configured display property for each candidate
+- **Details presentation** → whatever surface the referenced detail view's own template produces; this component only ensures the child is rendered
+- **Display-only rendering** → the design system's read-only value display
+- **Inline form presentation** → no component; the referenced view's own template provides the layout
+- **Container** → a plain full-width wrapper; add no styling of your own
+
+## Generation Self-Check
+
+Before considering the component finished, confirm each of the following.
+
+- The node type is established before any presentation logic, and no component was generated for the inline form.
+- A `reference` node is correctly classified as an embedded record or a data reference before rendering.
+- The `inheritedProps` contract is documented and understood, with the merge idempotent and no top-level label read from the reference node.
+- No data page or parameter lookup exists anywhere in the component.
+- The option source is resolved from the `datasource` object's source entry, with its marker stripped, and treated as a path to another field on the same case.
+- The display property is taken from the `datasource` field map rather than assumed.
+- Selection copies the whole record into `targetPage`, not an identifier.
+- The details child is rendered.
+- Mode precedence is applied, so a read-only or display-only rendering ignores required, disabled and placeholder settings.
+- Every registry key the component reaches for is registered, including the types of every field in the details view.