@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 Composite field that dynamically renders a child component (Dropdown, AutoComplete, or SemanticLink) for referencing another Pega case or data object. Supports editable-in-review mode with direct case update.
 
-> **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 @@ Does NOT render a UI control directly. Instead, it reads the raw metadata to det
 
 - **Pega Name:** `ObjectReference`
 - **Type / Subtype:** `Field` / `Reference`
-- **Registration key:** `ObjectReference` (in `component-map.ts`)
+- **Registration key:** `ObjectReference` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-> Uses `Omit<PConnFieldProps, 'value'>` — no direct `value` prop.
+> Overrides the field input contract by omitting `value` — no direct `value` input.
 
 | Prop                                 | Type      | Default | Description                                                      |
 | ------------------------------------ | --------- | ------- | ---------------------------------------------------------------- |
@@ -33,79 +33,20 @@ Does NOT render a UI control directly. Instead, it reads the raw metadata to det
 | `showPromotedFilters`                | `boolean` | `false` | Show promoted filters in child                                   |
 | `additionalFields`                   | `any`     | —       | Additional fields for read-only display                          |
 
-## Component Skeleton
+## Implementation Structure
 
 This is a composite/orchestrator component — it does NOT render its own UI control. It creates a child component (Dropdown, AutoComplete, SemanticLink, or SingleReferenceReadonly) via `getPConnect().createComponent()`.
 
-```typescript
-import { useMemo } from 'react';
-import { SELECTION_MODE, generateColumns, getDataRelationshipContextFromKey } from './utils';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface ObjectReferenceProps extends Omit<PConnFieldProps, 'value'> {
-  getPConnect: any;
-  displayMode;
-  allowAndPersistChangesInReviewMode: any;
-  targetObjectType: any;
-  mode: string;
-  parameters: object;
-  hideLabel: boolean;
-  inline: boolean;
-  showPromotedFilters: boolean;
-  additionalFields: any;
-}
-
-export default function ObjectReference(props: ObjectReferenceProps) {
-  // 1. Destructure props
-  const {
-    getPConnect, displayMode,
-    allowAndPersistChangesInReviewMode: editableInReview = false,
-    targetObjectType, mode = '', parameters,
-    hideLabel = false, inline = false,
-    showPromotedFilters = false, additionalFields,
-  } = props;
-
-  // 2. Registry lookup
-  const SingleReferenceReadonly = getComponentFromRegistry('SingleReferenceReadOnly');
-
-  // 3. Setup
-  const pConn = getPConnect();
-  const referenceType = targetObjectType === 'case' ? 'Case' : 'Data';
-  const rawViewMetadata = pConn.getRawMetadata();
-  const refFieldMetadata = pConn.getFieldMetadata(
-    rawViewMetadata?.config?.value?.split('.', 2)[1]
-  );
-  const propsToUse = { ...pConn.getInheritedProps(), ...props };
-  const isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY';
-  const canBeChangedInReviewMode = editableInReview &&
-    ['Autocomplete', 'Dropdown'].includes(rawViewMetadata.config.componentType);
-
-  // 4. onRecordChange handler — see Behavioral Contract
-  const onRecordChange = (event) => { /* ... */ };
-
-  // 5. recreatedFirstChild (useMemo) — the main logic
-  //    Decision tree:
-  //    a) SemanticLink && !canBeChangedInReviewMode → createComponent('SemanticLink', ...)
-  //    b) isDisplayModeEnabled && !canBeChangedInReviewMode → <SingleReferenceReadonly ... />
-  //    c) Editable: generateColumns, set deferDatasource, build fieldMetaData,
-  //       createComponent(type, { config with datasourceMetadata, onRecordChange, ... })
-  const recreatedFirstChild = useMemo(() => { /* ... */ }, [
-    rawViewMetadata.config?.datasource?.source,
-    parameters,
-    propsToUse.required,
-    propsToUse.disabled,
-    getPConnect().getPageReference(),
-  ]);
-
-  // 6. Return — minimal grid wrapper
-  return (
-    <GridContainer>
-      <GridItem>{recreatedFirstChild}</GridItem>
-    </GridContainer>
-  );
-}
-```
+**Module Setup:** The component depends on the project's component registry (to resolve `SingleReferenceReadOnly`) and local utility helpers (`SELECTION_MODE`, `generateColumns`, `getDataRelationshipContextFromKey`). Define the input contract by overriding the project's field input contract to omit `value`, and adding `getPConnect`, `displayMode`, `allowAndPersistChangesInReviewMode`, `targetObjectType`, `mode`, `parameters`, `hideLabel`, `inline`, `showPromotedFilters`, and `additionalFields`.
+
+**Main Component Logic** — steps in order:
+
+1. **Receive inputs** — `getPConnect`, `displayMode`, alias `allowAndPersistChangesInReviewMode` to `editableInReview` (default `false`), `targetObjectType`, `mode` (default `''`), `parameters`, `hideLabel` (default `false`), `inline` (default `false`), `showPromotedFilters` (default `false`), `additionalFields`.
+2. **Registry lookup** — resolve `SingleReferenceReadonly` (registry key `'SingleReferenceReadOnly'`) via the project's component registry.
+3. **Setup** — `pConn`; `referenceType` set to `'Case'` when `targetObjectType === 'case'`, else `'Data'`; `rawViewMetadata` via `pConn.getRawMetadata()`; `refFieldMetadata` via `pConn.getFieldMetadata()` on the second segment of the raw metadata's config value path; `propsToUse` merging `pConn.getInheritedProps()` with the component inputs; `isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY'`; `canBeChangedInReviewMode` true when `editableInReview` is set and the raw metadata's `config.componentType` is `'Autocomplete'` or `'Dropdown'`.
+4. **`onRecordChange` handler** — see the Behavioral Contract section below for its full logic.
+5. **`recreatedFirstChild`** (memoized computation) — the main decision-tree logic: (a) when the component type is `SemanticLink` and not editable-in-review, create a `SemanticLink` child via `createComponent`; (b) when in display mode and not editable-in-review, render `SingleReferenceReadonly`; (c) otherwise (editable), call `generateColumns`, set `deferDatasource`, build `fieldMetaData`, and create the appropriate child (`Dropdown` or `AutoComplete`) via `createComponent` with a config object carrying the datasource metadata, `onRecordChange`, and related inputs. Dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
+6. **Return** — a minimal grid wrapper containing `recreatedFirstChild`.
 
 ## Behavioral Contract
 
@@ -114,7 +55,7 @@ export default function ObjectReference(props: ObjectReferenceProps) {
 1. `referenceType = targetObjectType === 'case' ? 'Case' : 'Data'`
 2. `rawViewMetadata = pConn.getRawMetadata()` — the raw component metadata from Pega config
 3. `refFieldMetadata = pConn.getFieldMetadata(rawViewMetadata?.config?.value?.split('.', 2)[1])`
-4. `propsToUse = { ...pConn.getInheritedProps(), ...props }` — merged inherited + local props
+4. `propsToUse = { ...pConn.getInheritedProps(), ...componentInputs }` — merged inherited + local inputs
 5. `isDisplayModeEnabled = displayMode === 'DISPLAY_ONLY'`
 6. `canBeChangedInReviewMode = editableInReview && ['Autocomplete', 'Dropdown'].includes(rawViewMetadata.config.componentType)`
 
@@ -146,33 +87,9 @@ Render `<SingleReferenceReadonly>` with config from `rawViewMetadata.config`, pa
    - `rawViewMetadata.config.showPromotedFilters = showPromotedFilters`
    - If `!canBeChangedInReviewMode`: set `rawViewMetadata.config.displayMode = displayMode`
 
-3. **Build fieldMetaData:**
-
-   ```
-   fieldMetaData = { datasourceMetadata: { datasource: { parameters: {} } } }
-   ```
-   - Set `propertyForDisplayText` from `datasource.fields.text` (strip `@P ` prefix)
-   - Set `propertyForValue` from `datasource.fields.value` (strip `@P ` prefix)
-   - Set `name` from `referenceList`
-   - If `rawViewMetadata.config.parameters`: assign `parameters` prop
-
-4. **Create child component:**
-   ```
-   getPConnect().createComponent({
-     type,  // 'Dropdown' or 'AutoComplete'
-     config: {
-       ...rawViewMetadata.config,
-       descriptors: mode === SELECTION_MODE.SINGLE ? refFieldMetadata?.descriptors : null,
-       datasourceMetadata: fieldMetaData.datasourceMetadata,
-       required, visibility, disabled, label, parameters, readOnly: false,
-       localeReference, referenceType (for single mode only),
-       contextClass: targetObjectClass,
-       primaryField: displayField,
-       dataRelationshipContext,
-       hideLabel, onRecordChange, inline
-     }
-   })
-   ```
+3. **Build fieldMetaData:** Start from an object shaped as `{ datasourceMetadata: { datasource: { parameters: {} } } }`. Set `propertyForDisplayText` from `datasource.fields.text` (with any leading `@P ` prefix stripped). Set `propertyForValue` from `datasource.fields.value` (with any leading `@P ` prefix stripped). Set `name` from `referenceList`. If `rawViewMetadata.config.parameters` is present, assign it to the `parameters` property.
+
+4. **Create child component:** Call `getPConnect().createComponent()` with `type` set to `'Dropdown'` or `'AutoComplete'`, and a `config` object spreading `rawViewMetadata.config` plus: `descriptors` (from `refFieldMetadata?.descriptors` when `mode === SELECTION_MODE.SINGLE`, otherwise `null`), `datasourceMetadata` (from `fieldMetaData.datasourceMetadata`), `required`, `visibility`, `disabled`, `label`, `parameters`, `readOnly: false`, `localeReference`, `referenceType` (for single mode only), `contextClass` (the target object class), `primaryField` (the display field), `dataRelationshipContext`, `hideLabel`, `onRecordChange`, and `inline`.
 
 ### `onRecordChange` handler
 
@@ -190,7 +107,7 @@ Called when user selects a new value in editable/editable-in-review mode:
 
 ### Memoization
 
-`recreatedFirstChild` is memoized with `useMemo` — dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
+`recreatedFirstChild` is a memoized computation — dependencies: `rawViewMetadata.config?.datasource?.source`, `parameters`, `propsToUse.required`, `propsToUse.disabled`, `getPConnect().getPageReference()`.
 
 ## Display Mode Rendering
 
@@ -198,50 +115,35 @@ Display mode is passed through to the child component — the child (Dropdown, A
 
 ## Visual Specifications
 
-ObjectReference itself renders a minimal grid container:
-
-```
-<Grid container>
-  <Grid>{recreatedFirstChild}</Grid>
-</Grid>
-```
+ObjectReference itself renders a minimal grid container: a grid wrapping a single grid item that holds `recreatedFirstChild`.
 
 The visual appearance is entirely determined by the child component being rendered. No additional styling is applied by `ObjectReference` itself.
 
-**CSS-only implementation:**
-
-```css
-.object-reference-container {
-  display: grid;
-  width: 100%;
-}
-```
+**Visual-only styling notes:** The outer container uses a full-width grid layout with a single column.
 
 ## Edge Cases & Special Logic
 
 - **`generateColumns`**: a utility from `./utils` that populates `rawViewMetadata.config` with proper column definitions for the child Dropdown/AutoComplete.
 - **`getDataRelationshipContextFromKey`**: extracts the relationship context from a field key (also from `./utils`).
 - `rawViewMetadata.config` is mutated in place before being passed to `createComponent` — this is intentional but means the component re-creates the child on relevant prop changes.
-- For `SemanticLink` type, the child is created via `createComponent`, not rendered as a direct React element.
+- For `SemanticLink` type, the child is created via `createComponent`, not rendered as a direct element.
 - `SELECTION_MODE.SINGLE` and `SELECTION_MODE.MULTI` constants from `./utils`.
 
 ## Dependencies
 
-- `SELECTION_MODE`, `generateColumns`, `getDataRelationshipContextFromKey` from `./utils` (local).
-- `getComponentFromRegistry('SingleReferenceReadOnly')` — for display-only non-SemanticLink.
+- Local utility helpers: `SELECTION_MODE`, `generateColumns`, `getDataRelationshipContextFromKey`.
+- The project's component registry, resolving `SingleReferenceReadOnly` — for display-only non-SemanticLink.
 - `PCore.getCaseUtils()`, `PCore.getAnnotationUtils()`, `PCore.getContainerUtils()` — for editable-in-review updates.
-- `useMemo` from React.
-- No `handleEvent` — selection handling is done by the child component via `onRecordChange`.
+- No event-commit utility — selection handling is done by the child component via `onRecordChange`.
 
 ## Design System Mapping
 
 **UI control type:** Composite wrapper — renders Dropdown, AutoComplete, SemanticLink, or SingleReferenceReadonly. No dedicated UI control.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Scenario                                              | Rendered Child                      |
-| ----------------------------------------------------- | ----------------------------------- |
-| `componentType='Dropdown'` (editable)                 | `Dropdown` component                |
-| `componentType='AutoComplete'` (editable)             | `AutoComplete` component            |
-| `componentType='SemanticLink'`                        | `SemanticLink` component            |
-| `displayMode='DISPLAY_ONLY'` (non-editable-in-review) | `SingleReferenceReadonly` component |
+- **Editable Dropdown/AutoComplete** → child created via `getPConnect().createComponent()` with datasource metadata
+- **SemanticLink** → child created via `createComponent` with case reference config
+- **Display-only** → render `SingleReferenceReadonly` from the project's component registry
+- **Editable-in-review** → allow editing with direct case update via `PCore.getCaseUtils()`
+- **Grid wrapper** → use a simple container to hold the `recreatedFirstChild`

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

@@ -2,7 +2,7 @@
 
 Percentage numeric input with a `%` suffix and locale-aware decimal/thousands separators.
 
-> **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,123 +14,60 @@ Renders a numeric input for percentage values. Always appends a `%` suffix in th
 
 - **Pega Name:** `Percentage`
 - **Type / Subtype:** `Field` / `Decimal-Percentage`
-- **Registration key:** `Percentage` (in `component-map.ts`)
+- **Registration key:** `Percentage` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-| Prop                  | Type                | Default | Description                                                                                      |
+| Name                  | Type                | Default | Description                                                                                      |
 | --------------------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------ |
 | `currencyISOCode`     | `string` (optional) | `'USD'` | ISO code used for locale-aware decimal/thousands separator lookup only (not for currency symbol) |
 | `showGroupSeparators` | `string` (optional) | —       | Whether to show thousands separators (passed as string, truthy check applies)                    |
 | `decimalPrecision`    | `number` (optional) | —       | Number of decimal places                                                                         |
 
-## Component Skeleton
-
-Follow this exact structure. Nearly identical to Currency but with `suffix='%'` instead of prefix, and no `fixedDecimalScale`.
-
-```typescript
-import { useEffect, useState } from 'react';
-import { getCurrencyCharacters, getCurrencyOptions } from '../Currency/currency-utils';
-import handleEvent from '../../helpers/event-utils';
-import { format } from '../../helpers/formatters';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '@pega/sdk-react';
-
-interface PercentageProps extends PConnFieldProps {
-  currencyISOCode?: string;
-  showGroupSeparators?: string;
-  decimalPrecision?: number;
-}
-
-export default function Percentage(props: PercentageProps) {
-  // 1. Registry lookup
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  // 2. Destructure props
-  const {
-    getPConnect, label, required, disabled, value = '',
-    validatemessage, status, readOnly, currencyISOCode = 'USD',
-    testId, helperText, displayMode, hideLabel, placeholder,
-    showGroupSeparators, decimalPrecision,
-  } = props;
-
-  // 3. State
-  const [values, setValues] = useState(value.toString());
-
-  // 4. PConnect setup
-  const pConn = getPConnect();
-  const actions = pConn.getActionsApi();
-  const propName = (pConn.getStateProps() as any).value;
-  const helperTextToDisplay = validatemessage || helperText;
-
-  // 5. Formatted value (computed eagerly, before display mode check)
-  const theCurrencyOptions = getCurrencyOptions(currencyISOCode);
-  const formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), theCurrencyOptions);
-
-  // 6. useEffect: sync from store — deps: [value]
-  useEffect(() => { setValues(value.toString()); }, [value]);
-
-  // 7. Read-only prop
-  let readOnlyProp = {};
-  if (readOnly) readOnlyProp = { readOnly: true };
-
-  // 8. Display mode returns
-  if (displayMode === 'DISPLAY_ONLY') {
-    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} />;
-  }
-  if (displayMode === 'STACKED_LARGE_VAL') {
-    return <FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant="stacked" />;
-  }
-
-  // 9. Test ID + separators (computed AFTER display mode check in actual code)
-  const testProps: any = { 'data-test-id': testId };
-  const theSymbols = getCurrencyCharacters(currencyISOCode);
-  const theCurrDec = theSymbols.theDecimalIndicator;
-  const theCurrSep = theSymbols.theDigitGroupSeparator;
-
-  // 10. Event handlers
-  function PercentageOnBlur() { handleEvent(actions, 'changeNblur', propName, values); }
-  const handleChange = (val) => { setValues(val.value); };
-
-  // 11. Main render — numeric format input with % suffix
-  //     Key props:
-  //     - valueIsNumericString: true, fullWidth: true
-  //     - value: values, suffix: '%'
-  //     - variant: readOnly ? 'standard' : 'outlined'
-  //     - decimalSeparator: theCurrDec
-  //     - thousandSeparator: showGroupSeparators ? theCurrSep : ''
-  //     - decimalScale: decimalPrecision
-  //     - onValueChange, onBlur: !readOnly ? PercentageOnBlur : undefined
-  //     - label, helperText: helperTextToDisplay, placeholder: placeholder ?? ''
-  //     - required, disabled, error: status === 'error', size: 'small'
-  //     - slotProps: { input: { ...readOnlyProp, inputProps: { ...testProps } } }
-  return <NumericFormatInput ... />;
-}
-```
+All other inputs come from the project's field input contract (see prerequisite skill).
+
+## Implementation Structure
+
+Nearly identical to Currency but with a `%` suffix instead of a prefix, and no fixed decimal scale.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `FieldValueList`), the project's event-commit utility, the project's currency utility helpers (for decimal/separator lookup), and the project's formatting helpers (for display-mode value formatting). It also uses a numeric-format masking library for locale-aware input display. Define the input contract as an extension of the project's field input contract, adding optional `currencyISOCode`, `showGroupSeparators`, and `decimalPrecision` fields.
+
+**Main Component Logic** — steps in order:
+
+1. **Registry lookup** — resolve `FieldValueList` via the project's component registry.
+2. **Receive inputs** — `getPConnect`, `label`, `required`, `disabled`, `value` (default `''`), `validatemessage`, `status`, `readOnly`, `currencyISOCode` (default `'USD'`), `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`, `showGroupSeparators`, `decimalPrecision`.
+3. **Local state** — `values` initialized from `value.toString()`.
+4. **PConnect setup** — obtain the PConnect instance, its actions API, and the bound property name; compute `helperTextToDisplay = validatemessage || helperText`.
+5. **Formatted value** — computed eagerly, before the display-mode check: obtain the currency formatting options via the project's currency options helper, then compute the formatted value using the project's formatting helper with the component's type name (from `pConn.getComponentName()?.toLowerCase()`) as the format key and the currency options.
+6. **Sync from store** — a lifecycle effect watching `value` updates `values` (as a string) whenever it changes.
+7. **Read-only flag** — build a read-only configuration, set to mark the input read-only only when `readOnly` is true.
+8. **Display mode returns** — `DISPLAY_ONLY` and `STACKED_LARGE_VAL` both return `FieldValueList` using the formatted value, the latter with a stacked variant.
+9. **Test ID and separators** — computed after the display-mode check: build a test-id attribute from `testId`; derive the decimal indicator and digit group separator via the project's currency utility helpers using `currencyISOCode`.
+10. **Event handlers** — the blur handler commits via the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`; the value-change handler updates `values` with the raw numeric string from the masking library's callback.
+11. **Render** — a numeric-format input configured with: value-is-numeric-string flag, full width, current `values`, suffix `'%'`, an outlined style when editable or flat/borderless style when read-only, decimal separator set to the locale-derived decimal indicator, thousands separator set to the locale-derived group separator only when `showGroupSeparators` is truthy (otherwise empty string), decimal scale set to `decimalPrecision`, the value-change handler, the blur handler wired only when not read-only, `label`, `helperText: helperTextToDisplay`, `placeholder: placeholder ?? ''`, `required`, `disabled`, an error state when `status === 'error'`, small size, and the read-only/test-id attributes applied to the underlying input element.
 
 ## Behavioral Contract
 
 1. **Local state:** Maintain `values` (string). Initialize from `value.toString()`.
-2. **Sync from store:** `useEffect` watching `value` → `setValues(value.toString())`.
-3. **Separators:** Derive `decimalSeparator` and `thousandSeparator` from locale lookup using `currencyISOCode` (same as Currency/Decimal). Apply `thousandSeparator` only when `showGroupSeparators` is truthy.
+2. **Sync from store:** A lifecycle effect watching `value` updates `values` (converted to string).
+3. **Separators:** Derive the decimal separator and thousands separator from locale lookup using `currencyISOCode` (same as Currency/Decimal). Apply the thousands separator only when `showGroupSeparators` is truthy.
 4. **Suffix:** Always append `%` suffix to the numeric input.
-5. **Decimal scale:** Use `decimalPrecision` prop.
+5. **Decimal scale:** Use the `decimalPrecision` input.
 6. **No prefix:** Unlike Currency, no prefix symbol.
 7. **On value change:** Update local `values` state with the raw numeric string.
-8. **On blur:** Commit via `handleEvent(actions, 'changeNblur', propName, values)`.
-9. **Read-only:** Set `readOnly: true` on the input. Flat/borderless style. `onBlur` omitted.
+8. **On blur:** Commit via the project's event-commit utility with event type `'changeNblur'`, the property name, and `values`.
+9. **Read-only:** Set the read-only attribute on the input. Flat/borderless style. Blur handler omitted.
 
 ## Display Mode Rendering
 
-Format the value using the percentage formatter before display:
+Format the value using the project's formatting helper with the component's type name as the format key before display:
 
-- `formattedValue = format(value, pConn.getComponentName()?.toLowerCase(), currencyOptions)`
-- **`DISPLAY_ONLY`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} />`.
-- **`STACKED_LARGE_VAL`:** `<FieldValueList name={hideLabel ? '' : label} value={formattedValue} variant='stacked' />`.
+- **`DISPLAY_ONLY`:** Render `FieldValueList` with `name` set to `label` (or empty when `hideLabel` is true) and `value` set to the formatted value.
+- **`STACKED_LARGE_VAL`:** Render `FieldValueList` the same way, with a stacked layout variant.
 
 ## Read-Only Rendering
 
-Keep numeric format input with `readOnly: true` and `%` suffix still visible. Flat/borderless style.
+Keep the numeric format input with the read-only attribute and `%` suffix still visible. Flat/borderless style.
 
 ## Visual Specifications
 
@@ -139,11 +76,11 @@ Keep numeric format input with `readOnly: true` and `%` suffix still visible. Fl
 | Width               | 100%                                      |
 | Size                | Small                                     |
 | Variant editable    | Outlined                                  |
-| Variant read-only   | Standard (flat)                           |
+| Variant read-only   | Flat/borderless                           |
 | Suffix              | `%` (always shown after the value)        |
 | Thousands separator | Only when `showGroupSeparators` is truthy |
 | Decimal scale       | `decimalPrecision`                        |
-| Placeholder         | From `placeholder` prop                   |
+| Placeholder         | From the `placeholder` input              |
 | Error state         | Red border + red helper text              |
 
 **CSS-only notes:** Achieve the `%` suffix by wrapping the input in a relative container and absolutely positioning a `%` label at the right side, or using an input with a `::after` pseudo-element technique.
@@ -156,22 +93,21 @@ Keep numeric format input with `readOnly: true` and `%` suffix still visible. Fl
 
 ## Dependencies
 
-- Numeric formatting library (e.g., `react-number-format`'s `NumericFormat`).
-- `getCurrencyCharacters(currencyISOCode)` — for `theDecimalIndicator`, `theDigitGroupSeparator`.
-- `getCurrencyOptions(currencyISOCode)` — for `format()` call.
-- `format()` from `../../helpers/formatters`.
-- `handleEvent` from `../../helpers/event-utils`.
-- `getComponentFromRegistry('FieldValueList')` for display modes.
+- A numeric formatting library — handles locale-aware separators, suffix, and decimal scale.
+- The project's currency utility helpers — for decimal indicator and digit group separator lookup.
+- The project's currency options helper — for formatting options.
+- The project's formatting helpers — specifically the named `format` export (not a method on the default export). Use it as a standalone function, not as a property of the default-exported object.
+- The project's event-commit utility.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 
 ## Design System Mapping
 
 **UI control type:** Percentage numeric input with `%` suffix.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Design System      | Recommended Component                                           |
-| ------------------ | --------------------------------------------------------------- |
-| Default (CSS only) | `<input type="text">` + custom masking + `%` suffix span        |
-| MUI                | `NumericFormat` with `suffix='%'` and `customInput={TextField}` |
-| Ant Design         | `<InputNumber suffix="%" precision={decimalPrecision} />`       |
-| Chakra UI          | `<NumberInput>` + `<InputRightAddon>%</InputRightAddon>`        |
+- **Numeric format input** → use a numeric masking library compatible with the project's framework, or implement custom input masking
+- **`%` suffix** → use the DS's input suffix/adornment slot, or absolutely position a `%` label
+- **Decimal/thousands separators** → derive from the currency utility helpers based on the ISO code
+- **Read-only** → flat/borderless style with read-only attribute, suffix still visible
+- **Error state** → the DS's error/danger visual state