@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 User picker field that renders as either a search box (AutoComplete) or a dropdown, populated from the Pega operators data page.
 
-> **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,15 +14,11 @@ Renders a user selection field. Can display as a typeahead search box or a dropd
 
 - **Pega Name:** `UserReference`
 - **Type / Subtype:** `Field` / `Text-UserReference`
-- **Registration key:** `UserReference` (in `component-map.ts`)
+- **Registration key:** `UserReference` (in the project's component map)
 
-## Props (component-specific)
+## Inputs (component-specific)
 
-> Extends `PConnProps` (NOT `PConnFieldProps` — field-specific props are defined manually):
-
-```typescript
-import type { PConnProps } from '@pega/sdk-react';
-```
+> Extends the project's base component interface (NOT the field input contract — field-specific inputs are defined manually).
 
 | Prop                  | Type                 | Default    | Description                                                      |
 | --------------------- | -------------------- | ---------- | ---------------------------------------------------------------- |
@@ -38,100 +34,27 @@ import type { PConnProps } from '@pega/sdk-react';
 | `required`            | `boolean` (optional) | `false`    |                                                                  |
 | `validatemessage`     | `string` (optional)  | `''`       | Validation error message                                         |
 | `showAsFormattedText` | `boolean` (optional) | `false`    | When `true` in read-only mode, show formatted user name text     |
-| `additionalProps`     | `object` (optional)  | `{}`       | Extra props forwarded to the child component                     |
+| `additionalProps`     | `object` (optional)  | `{}`       | Extra inputs forwarded to the child component                    |
 | `hideLabel`           | `boolean` (optional) | `false`    |                                                                  |
 | `variant`             | `string` (optional)  | `'inline'` | Layout variant                                                   |
 | `onChange`            | `any` (optional)     | —          | Change handler (passed through to child)                         |
 
-## Component Skeleton
-
-Orchestrator component — renders either AutoComplete, Dropdown, formatted text, or FieldValueList based on mode. Uses `memo` with custom comparison.
-
-```typescript
-import { memo, useEffect, useState } from 'react';
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
-import { getUserId, isUserNameAvailable } from './UserReferenceUtils';
-
-const DROPDOWN_LIST = 'Drop-down list';
-const SEARCH_BOX = 'Search box';
-
-interface UserReferenceProps extends PConnProps {
-  displayAs?: string;
-  displayMode?: string;
-  label?: string;
-  value?: any;
-  testId?: string;
-  placeholder?: string;
-  helperText?: string;
-  disabled?: boolean;
-  readOnly?: boolean;
-  required?: boolean;
-  validatemessage?: string;
-  showAsFormattedText?: boolean;
-  additionalProps?: object;
-  hideLabel?: boolean;
-  variant?: string;
-  onChange?: any;
-}
-
-const UserReference = (props: UserReferenceProps) => {
-  // 1. Registry lookups
-  const AutoComplete = getComponentFromRegistry('AutoComplete');
-  const Dropdown = getComponentFromRegistry('Dropdown');
-  const FieldValueList = getComponentFromRegistry('FieldValueList');
-
-  // 2. Destructure props (all with defaults)
-  const {
-    label = '',
-    displayAs = '',
-    displayMode = '',
-    getPConnect,
-    value = '',
-    testId = '',
-    helperText = '',
-    validatemessage = '',
-    placeholder = '',
-    showAsFormattedText = false,
-    additionalProps = {},
-    hideLabel = false,
-    readOnly = false,
-    required = false,
-    disabled = false,
-    onChange,
-  } = props;
-
-  // 3. State
-  const [dropDownDataSource, setDropDownDataSource] = useState([]);
-  const [userName, setUserName] = useState('');
-
-  // 4. Derived
-  const OPERATORS_DP = PCore.getEnvironmentInfo().getDefaultOperatorDP();
-  const userId = getUserId(value);
-
-  // 5. useEffect — deps: [displayAs, readOnly, showAsFormattedText, value]
-  //    Case 1: userId && readOnly && showAsFormattedText → resolve userName
-  //    Case 2: displayAs === DROPDOWN_LIST → fetch user list via REST
-
-  // 6. Rendering decision tree
-  //    displayMode DISPLAY_ONLY → FieldValueList(userName || '')
-  //    displayMode STACKED → FieldValueList(userName || '', variant='stacked')
-  //    readOnly && showAsFormattedText && userId → label + userName text
-  //    displayAs SEARCH_BOX → <AutoComplete datasource={OPERATORS_DP} listType='datapage' ...>
-  //    displayAs DROPDOWN_LIST → <Dropdown datasource={dropDownDataSource} listType='associated' ...>
-  return userReferenceComponent;
-};
-
-// 7. Memo with custom comparison
-const comparisonFn = (prevProps, nextProps) =>
-  getUserId(prevProps.value) === getUserId(nextProps.value) &&
-  prevProps.validatemessage === nextProps.validatemessage &&
-  prevProps.required === nextProps.required &&
-  prevProps.disabled === nextProps.disabled &&
-  prevProps.readOnly === nextProps.readOnly;
-
-export default memo(UserReference, comparisonFn);
-```
+## Implementation Structure
+
+Orchestrator component — renders either AutoComplete, Dropdown, formatted text, or FieldValueList based on mode. Wrapped in a memoization wrapper with a custom comparison function.
+
+**Module Setup:** The component depends on the project's component registry (to resolve `AutoComplete`, `Dropdown`, and `FieldValueList`) and local utility helpers (`getUserId` and `isUserNameAvailable`). It also uses `PCore.getUserApi()`, `PCore.getRestClient()`, and `PCore.getEnvironmentInfo()` for user data resolution. Define two constants: `DROPDOWN_LIST = 'Drop-down list'` and `SEARCH_BOX = 'Search box'`. Define the input contract as an extension of the project's base component interface with all the optional fields listed in the inputs table above.
+
+**Main Component Logic** (defined as an arrow function, not a plain function declaration) — steps in order:
+
+1. **Registry lookups** — resolve `AutoComplete`, `Dropdown`, and `FieldValueList` via the project's component registry.
+2. **Receive inputs (all with defaults)** — `label` (default `''`), `displayAs` (default `''`), `displayMode` (default `''`), `getPConnect`, `value` (default `''`), `testId` (default `''`), `helperText` (default `''`), `validatemessage` (default `''`), `placeholder` (default `''`), `showAsFormattedText` (default `false`), `additionalProps` (default `{}`), `hideLabel` (default `false`), `readOnly` (default `false`), `required` (default `false`), `disabled` (default `false`), `onChange`.
+3. **Local state** — `dropDownDataSource` (array, default `[]`) and `userName` (string, default `''`).
+4. **Derived values** — `OPERATORS_DP = PCore.getEnvironmentInfo().getDefaultOperatorDP()` (the default operators data page name) and `userId = getUserId(value)`.
+5. **Mount/update effect** — a lifecycle effect with dependencies `[displayAs, readOnly, showAsFormattedText, value]`, handling two cases (see Behavioral Contract below for the exact branching logic): resolving the display username when in read-only formatted-text mode, or fetching the dropdown data source when `displayAs === 'Drop-down list'`.
+6. **Rendering decision tree** (see Behavioral Contract below for the exact order): `DISPLAY_ONLY` returns `FieldValueList(userName || '')`; `STACKED_LARGE_VAL` returns the stacked variant; read-only formatted text mode returns a label + username text block; `'Search box'` mode renders `AutoComplete`; `'Drop-down list'` mode renders `Dropdown`.
+
+**Export:** wrap the component in a memoization wrapper with a custom comparison function (see "Re-render optimization" below).
 
 ## Behavioral Contract
 
@@ -144,7 +67,7 @@ export default memo(UserReference, comparisonFn);
 - `dropDownDataSource` (array): populated when `displayAs === 'Drop-down list'`
 - `userName` (string): resolved display name for formatted text mode
 
-### Mount effect: `useEffect([displayAs, readOnly, showAsFormattedText, value])`
+### Mount effect: lifecycle effect watching `[displayAs, readOnly, showAsFormattedText, value]`
 
 **Case 1: `userId && readOnly && showAsFormattedText`**
 
@@ -161,33 +84,13 @@ export default memo(UserReference, comparisonFn);
 
 ### Rendering decision tree
 
-```
-if displayMode === 'DISPLAY_ONLY' → FieldValueList(userName || '')
-if displayMode === 'STACKED_LARGE_VAL' → FieldValueList(userName || '', variant='stacked')
-if readOnly && showAsFormattedText && userId → formatted text label+body
-else if displayAs === 'Search box' → AutoComplete component
-else if displayAs === 'Drop-down list' → Dropdown component
-```
+Evaluated in this order: if `displayMode === 'DISPLAY_ONLY'`, render `FieldValueList(userName || '')`; else if `displayMode === 'STACKED_LARGE_VAL'`, render the stacked `FieldValueList` variant; else if `readOnly && showAsFormattedText && userId`, render the formatted text block; else if `displayAs === 'Search box'`, render the `AutoComplete` component; else if `displayAs === 'Drop-down list'`, render the `Dropdown` component.
 
 ### Subsection: Search box mode (`displayAs === 'Search box'`)
 
-Render `AutoComplete` with hardcoded columns for operator search:
+Render `AutoComplete` with hardcoded columns for operator search: a primary column on `pyUserName` (displayed, used for search, marked primary), and a secondary key column on `pyUserIdentifier` (displayed, used for search, marked secondary, with `setProperty: 'Associated property'` and `key: 'true'`).
 
-```typescript
-columns = [
-  { value: 'pyUserName', display: 'true', useForSearch: true, primary: 'true' },
-  {
-    value: 'pyUserIdentifier',
-    setProperty: 'Associated property',
-    key: 'true',
-    display: 'true',
-    secondary: 'true',
-    useForSearch: 'true',
-  },
-];
-```
-
-Props: `datasource={OPERATORS_DP}`, `listType='datapage'`, `value={userId}`, plus label/placeholder/readOnly/disabled/required/helperText/validatemessage/hideLabel/onChange/additionalProps/testId.
+Inputs: `datasource` set to `OPERATORS_DP`, `listType='datapage'`, `value` set to `userId`, plus label/placeholder/readOnly/disabled/required/helperText/validatemessage/hideLabel/onChange/additionalProps/testId.
 
 ### Subsection: Dropdown mode (`displayAs === 'Drop-down list'`)
 
@@ -196,33 +99,15 @@ Render `Dropdown` with:
 - `datasource={dropDownDataSource}` (fetched user list)
 - `listType='associated'`
 - `value={userId}`
-- Plus same field props as above
+- Plus same field inputs as above
 
 ### Subsection: Formatted text read-only (`readOnly && showAsFormattedText && userId`)
 
-Render a label + name display:
-
-```html
-<div>
-  <caption-text>{label}</caption-text>
-  <body-text>{userName}</body-text>
-</div>
-```
+Render a small wrapper containing a caption-style text element showing `label`, followed by a body-style text element showing `userName`.
 
 ### Re-render optimization
 
-Export with `memo` using custom comparison `comparisonFn`:
-
-```typescript
-const comparisonFn = (prevProps, nextProps) =>
-  getUserId(prevProps.value) === getUserId(nextProps.value) &&
-  prevProps.validatemessage === nextProps.validatemessage &&
-  prevProps.required === nextProps.required &&
-  prevProps.disabled === nextProps.disabled &&
-  prevProps.readOnly === nextProps.readOnly;
-```
-
-`export default memo(UserReference, comparisonFn)`
+Export with a memoization wrapper using a custom comparison function that returns `true` (skip re-render) only when all of the following are equal between previous and next inputs: `getUserId(value)` (resolved on both sides), `validatemessage`, `required`, `disabled`, and `readOnly`.
 
 ## Display Mode Rendering
 
@@ -247,18 +132,7 @@ The visual appearance is determined by the child component rendered:
 | Name     | Body text (normal size)                                   |
 | Spacing  | Standard form field spacing                               |
 
-**CSS-only for formatted text:**
-
-```css
-.user-reference-label {
-  font-size: 0.75rem;
-  color: rgba(0, 0, 0, 0.6);
-  margin-bottom: 4px;
-}
-.user-reference-name {
-  font-size: 1rem;
-}
-```
+**Visual-only styling notes for formatted text:** The label is rendered in caption-size text (0.75rem) with a muted secondary color and a small bottom margin (4px) separating it from the name. The name is rendered in standard body text size (1rem).
 
 ## Edge Cases & Special Logic
 
@@ -270,11 +144,11 @@ The visual appearance is determined by the child component rendered:
 
 ## Dependencies
 
-- `memo` from React.
-- `getUserId`, `isUserNameAvailable` from `./UserReferenceUtils` (local utility).
-- `getComponentFromRegistry('AutoComplete')` — for search box mode.
-- `getComponentFromRegistry('Dropdown')` — for dropdown mode.
-- `getComponentFromRegistry('FieldValueList')` — for display modes.
+- A memoization wrapper from the framework.
+- Local utility helpers: `getUserId`, `isUserNameAvailable`.
+- The project's component registry, resolving `AutoComplete` — for search box mode.
+- The project's component registry, resolving `Dropdown` — for dropdown mode.
+- The project's component registry, resolving `FieldValueList` — for display modes.
 - `PCore.getUserApi().getOperatorDetails()` — for async user name resolution.
 - `PCore.getRestClient().invokeRestApi('getListData', ...)` — for dropdown data source.
 - `PCore.getEnvironmentInfo().getDefaultOperatorDP()` — for operators data page name.
@@ -283,11 +157,10 @@ The visual appearance is determined by the child component rendered:
 
 **UI control type:** User picker — delegates to AutoComplete or Dropdown for the actual input.
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| Mode                     | Underlying control                |
-| ------------------------ | --------------------------------- |
-| Search box               | AutoComplete (combobox/typeahead) |
-| Drop-down list           | Dropdown (select)                 |
-| Formatted text read-only | Label + text display              |
-| Display mode             | FieldValueList                    |
+- **Search box mode** → render the `AutoComplete` component with operator columns
+- **Dropdown mode** → render the `Dropdown` component with the fetched operator list
+- **Formatted text read-only** → render a label + text display (caption + body text)
+- **Display mode** → render `FieldValueList` with the resolved username
+- **Memoization** → wrap the component with a custom comparison to avoid unnecessary re-renders

package/templates/react-sdk-reference/.ai-common/skills/infra-components.md

@@ -0,0 +1,165 @@
+# Skill: Infrastructure (Chrome) Components
+
+Create or replace infrastructure components in the project. Infrastructure components are the chrome the Pega runtime draws _around_ a case or an assignment — the action button row, the stage progress indicator, the step navigation — rather than the fields inside it. Most of them ship from the SDK adapter package and are never generated. Three are overridable, because they render inline with the form where SDK styling is the most visible mismatch.
+
+---
+
+## Architecture Overview
+
+Each infrastructure component lives in its own folder under the project's infrastructure components directory, named after the component. The folder typically contains: the component implementation file; optionally a re-export module; and optionally a companion stylesheet.
+
+Infrastructure components differ from every other category in one important way: **they already exist**. Generating one produces an override that replaces the SDK's implementation. The Pega runtime keeps calling it with the contract it already uses, so the contract is not yours to design — only the markup and the styling are.
+
+---
+
+## What May Be Generated
+
+| Component         | Role                                                 | Generate? |
+| ----------------- | ---------------------------------------------------- | --------- |
+| `ActionButtons`   | The Cancel / Save / Submit row beneath an assignment | Yes       |
+| `Stages`          | The case stage progress indicator                    | Yes       |
+| `MultiStep`       | Step navigation within a multi-step assignment       | Yes       |
+| `NavBar`          | Portal navigation shell                              | No        |
+| `DeferLoad`       | Deferred content loader                              | No        |
+| `VerticalTabs`    | Case view tab rail                                   | No        |
+| `DashboardFilter` | Dashboard filtering controls                         | No        |
+
+The four marked "No" are structural plumbing tied to the SDK's own internals. Leave them to the SDK. If a request names one of them, skip it and say why.
+
+---
+
+## Input Contract
+
+**The three overridable components do not share an input shape.** This is the only category where that is true, so there is no single base contract to extend. Take each one's inputs from its own skill file.
+
+| Component       | Receives the PConnect accessor? | Other inputs                                                         |
+| --------------- | ------------------------------- | -------------------------------------------------------------------- |
+| `ActionButtons` | No                              | Two button-definition arrays and a press callback                    |
+| `Stages`        | Yes                             | The raw stage list                                                   |
+| `MultiStep`     | Yes                             | Child content, an item key, button definitions, and a press callback |
+
+`ActionButtons` is the exception to the rule that every Pega component receives the PConnect accessor. It is handed plain display props by its parent and must not attempt to reach the runtime for its own data.
+
+---
+
+## Implementation Patterns
+
+### Display-Only Chrome (no PConnect accessor)
+
+The component receives everything it needs as inputs and reports interaction back through a callback. It holds no local state and reads nothing from the store.
+
+**Module Setup:** The component depends only on the design system's presentation primitives and the Pega locale utilities. Define the input contract as a plain input shape — it does not extend the project's base component interface, because no PConnect accessor is supplied.
+
+**Main Component Logic** — steps in order:
+
+1. Receive the input arrays and the callback. Treat every array input as optional and default it to empty.
+2. Localize every label through the Pega locale utilities using the locale category the SDK component uses. Never render a raw input string as a label, and never hardcode label text.
+3. Render the design system's primitives for each entry.
+4. On interaction, invoke the supplied callback with exactly the arguments the SDK component passes. The callback signature is fixed by the runtime.
+
+### Case-Aware Chrome (PConnect accessor, read-only)
+
+The component receives the accessor so it can read case state and localize, but it never writes. It renders a derived view of data the runtime supplies.
+
+**Module Setup:** The component depends on the design system's presentation primitives. Define the input contract as an extension of the project's base component interface.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `getPConnect` plus the component's own inputs; call `getPConnect()` into `pConn`.
+2. Normalize the raw input through the SDK utility the component is documented to use. The runtime supplies unfiltered data; the utility decides what is displayable.
+3. Read any case-level state the component needs from `pConn`, using the runtime's constants rather than literal property names.
+4. Derive a display model — one entry per item, carrying its localized label and its state flags — before rendering. Keep derivation separate from markup so the same logic survives a design system change.
+5. Render the derived model. Do not commit anything to the store; this component is display-only.
+
+### Container Chrome (renders children and resolves sub-components)
+
+The component wraps the form content the runtime hands it and arranges other Pega components around it.
+
+**Module Setup:** The component depends on the design system's presentation primitives and the project's component registry. Define the input contract as an extension of the project's base component interface.
+
+**Main Component Logic** — steps in order:
+
+1. Resolve every Pega sub-component from the project's component registry, never by direct import. The registry is what lets a customer's own version win.
+2. Receive `getPConnect`, the child content, and the component's own inputs.
+3. Derive which part of the structure is active from the state flags the runtime supplies, applying the documented fallback when nothing is marked active.
+4. Render the surrounding structure, and render the child content only inside the active part.
+5. Forward the accessor, the item key, the button definitions and the press callback to the resolved sub-component unchanged. Do not reshape them.
+
+---
+
+## Localization
+
+Every label an infrastructure component renders comes from Pega, not from the component.
+
+- Button and action labels use `PCore.getLocaleUtils().getLocaleValue(name, category)` with the locale category the SDK component uses.
+- Case and stage names use `pConn.getLocalizationService().getLocalizedText(name)`.
+
+The value arriving in the input is a key, not display text. Rendering it directly will look correct in an English environment and break in every other one.
+
+---
+
+## Resolving Other Components
+
+When an infrastructure component renders another Pega component, resolve it through the project's component registry rather than importing it. An override only takes effect if the components that render it look it up by name — importing a sub-component directly pins it to the SDK's version and silently discards the customer's.
+
+---
+
+## Design System Adaptation
+
+The runtime contract — inputs, callback signatures, derivation logic, and localization — is identical regardless of design system. Only the rendered markup changes.
+
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/infra-skills/<ComponentName>.md` contains a **Design System Mapping** section. Use it as a starting point.
+
+**2. If the chosen design system is not covered** — use the component purpose description to identify the appropriate primitives (button, stepper, breadcrumb, divider, list).
+
+**3. Discover the API from installed packages** — confirm component names and inputs from the design system's type declaration files before writing the render markup.
+
+**4. Common chrome UI primitive mapping:**
+
+| Chrome pattern                | Typical DS equivalent                                                      |
+| ----------------------------- | -------------------------------------------------------------------------- |
+| Action row                    | Button group, Toolbar, or a flex row of Buttons                            |
+| Primary / secondary buttons   | The DS's emphasis or variant inputs                                        |
+| Separator above an action row | Divider, Separator, or a bordered container                                |
+| Stage progression             | Breadcrumbs, Steps, or Stepper                                             |
+| Step navigation               | Stepper (horizontal and vertical variants)                                 |
+| Step state indicator          | The stepper's own completed / active / pending states, or a numbered badge |
+
+**5. Icons** — if the DS has a companion icon package, check its exports before using any icon name. Never guess icon names. Decorative icons must be hidden from assistive technology.
+
+---
+
+## Registration
+
+Register infrastructure overrides in the project's component map under the component's Pega name. Because the SDK's own components are contributed as a spread of built-in entries, **an override must appear after that spread** — an entry listed before it is replaced by the SDK's version and the override silently does nothing.
+
+Never remove the spread. It supplies the infrastructure components that are not overridable, and removing it breaks rendering entirely.
+
+---
+
+## Existing Infrastructure Components
+
+| Component       | Description                   | Key APIs                                                |
+| --------------- | ----------------------------- | ------------------------------------------------------- |
+| ActionButtons   | Assignment action button row  | `PCore.getLocaleUtils()`                                |
+| Stages          | Case stage progress indicator | `PCore.getSDKUtils()`, `PCore.getConstants().CASE_INFO` |
+| MultiStep       | Assignment step navigation    | `PCore.getSDKUtils()`, the project's component registry |
+| NavBar          | Portal navigation shell       | SDK-provided — not generated                            |
+| DeferLoad       | Deferred content loader       | SDK-provided — not generated                            |
+| VerticalTabs    | Case view tab rail            | SDK-provided — not generated                            |
+| DashboardFilter | Dashboard filter controls     | SDK-provided — not generated                            |
+
+---
+
+## Key Conventions
+
+1. **Default export** — Each component is exported as the module's default export, except where the component's own skill file documents otherwise.
+2. **The contract is fixed** — Inputs, callback signatures and localization come from the SDK component being replaced. Only markup and styling are yours to change.
+3. **Not every chrome component gets the accessor** — `ActionButtons` receives plain display props. Do not add a PConnect accessor to it.
+4. **Chrome is display-only** — These components report interaction through the callback they were given. None of them writes to the store directly.
+5. **Localize everything** — Labels arrive as keys. Resolve them through the Pega locale utilities or the localization service.
+6. **Resolve sub-components from the registry** — never by direct import, or customer overrides are discarded.
+7. **Register after the SDK spread** — an override listed before the spread has no effect.
+8. **Derive before rendering** — compute the display model from the runtime's raw inputs first, then render it. This is what keeps the component portable across design systems.
+9. **Keep repeated elements stable** — every item in a rendered collection needs a stable identity so the runtime can update the list without reordering the wrong entries.
+10. **Case chrome is not assignment chrome** — `Stages` belongs to the case view and never appears inside an embedded assignment. `ActionButtons` and `MultiStep` do.

package/templates/react-sdk-reference/.ai-common/skills/infra-skills/ActionButtons.md

@@ -0,0 +1,122 @@
+# Skill: ActionButtons
+
+Assignment action button row. Renders the secondary and primary actions available on the current assignment — typically Cancel, Save for later, and Submit — beneath the form content.
+
+> **Prerequisite skill:** [`infra-components.md`](../infra-components.md) — covers architecture, the override contract, localization, and registration conventions common to ALL infrastructure components.
+
+---
+
+## Component Purpose
+
+Displays the actions the Pega runtime has determined are available on the current assignment, split into a secondary group and a primary group, and reports the chosen action back to its parent. It is a pure display component: it decides nothing about which actions exist, what they do, or whether they are permitted.
+
+It renders wherever an assignment renders, which includes an embedded assignment. In an embedded flow it is the most visible piece of chrome, and therefore the one most worth generating in the customer's design system.
+
+## Pega Metadata
+
+- **Registration key:** `ActionButtons` (in the project's component map)
+- **Category:** Infrastructure — case chrome, overridable
+- **Extends:** Nothing. This component does **not** extend the project's base component interface and receives **no** PConnect accessor.
+- **Rendered by:** The SDK's assignment card, which resolves it from the component registry and supplies every input.
+
+> ⚠️ **CRITICAL — THIS COMPONENT RECEIVES NO PCONNECT ACCESSOR**
+>
+> Every other Pega component is handed `getPConnect`. This one is not. Do not add it to the input contract, do not attempt to read case state, and do not call the actions API. Everything the component needs arrives as a plain input, and the only thing it does with a user interaction is invoke the callback it was given.
+
+## Inputs
+
+| Prop                 | Type                                           | Required | Description                                                           |
+| -------------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------- |
+| `arMainButtons`      | `ActionButtonEntry[]`                          | No       | Primary actions (e.g. Submit). Default empty array                    |
+| `arSecondaryButtons` | `ActionButtonEntry[]`                          | No       | Secondary actions (e.g. Cancel, Save for later). Default empty array  |
+| `onButtonPress`      | `(action: string, buttonType: string) => void` | Yes      | Invoked when any button is activated. See the callback contract below |
+
+Each `ActionButtonEntry` carries:
+
+| Field      | Type     | Required | Description                                                                            |
+| ---------- | -------- | -------- | -------------------------------------------------------------------------------------- |
+| `name`     | `string` | Yes      | The label **key**, to be localized before display. Also serves as the entry's identity |
+| `jsAction` | `string` | Yes      | The action identifier passed back through the callback                                 |
+| `actionID` | `string` | No       | Additional runtime identifier. Not needed for rendering                                |
+
+## Implementation Structure
+
+**Module Setup:** The component depends only on the design system's button and separator primitives. Define the input contract as a plain input shape with the two arrays and the callback — it does not extend the project's base component interface.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `arMainButtons` (default empty array), `arSecondaryButtons` (default empty array), and `onButtonPress` from inputs.
+2. Resolve the localization helper once: `PCore.getLocaleUtils().getLocaleValue`, to be called with the button's `name` and the locale category `'Assignment'`.
+3. Render a horizontal separator above the button row.
+4. Render the button row as two groups: the **secondary group first**, then the **primary group**. Within each group, render one button per entry in the order supplied, keyed by the entry's `name`.
+5. Render each secondary entry using the design system's low-emphasis button treatment, and each primary entry using its high-emphasis treatment. The label is the localized value of the entry's `name`.
+6. On activation, invoke `onButtonPress` with the entry's `jsAction` and the literal group discriminator — `'secondary'` for a secondary entry, `'primary'` for a main entry.
+
+## Behavioral Contract
+
+### Callback Contract
+
+`onButtonPress(jsAction, buttonType)` — two positional string arguments, in this order:
+
+1. The activated entry's `jsAction` value, passed through unchanged.
+2. The group the entry belongs to: the literal `'primary'` for entries from `arMainButtons`, the literal `'secondary'` for entries from `arSecondaryButtons`.
+
+Both arguments are fixed by the runtime. Do not pass the entry object, the event, the index, or the localized label. Do not substitute the entry's `actionID` for its `jsAction`.
+
+### Localization
+
+Every label is resolved through `PCore.getLocaleUtils().getLocaleValue(name, 'Assignment')`. The `name` field is a key, not display text — rendering it directly produces untranslated labels in any non-default locale. The locale category is the literal `'Assignment'`; it is not derived from the case or the assignment.
+
+### Ordering
+
+The secondary group renders before the primary group. Within each group, entries render in the order the runtime supplied them. Do not sort, deduplicate, or re-prioritize.
+
+### Interaction Scope
+
+The component performs no action itself. It does not submit, cancel, validate, confirm, or navigate. It reports the interaction and stops. Any confirmation dialog, disabled state during submission, or navigation belongs to the parent.
+
+## Visual Specifications
+
+| Element          | Description                                                                     |
+| ---------------- | ------------------------------------------------------------------------------- |
+| Separator        | A full-width horizontal rule above the button row                               |
+| Row              | Secondary group aligned to the leading edge, primary group to the trailing edge |
+| Secondary button | Low-emphasis treatment — text or ghost button, no fill                          |
+| Primary button   | High-emphasis treatment — filled, with the design system's accent colour        |
+
+**CSS-only implementation notes (if implementing without design system button components):**
+
+- Separator: `border: none; border-top: 1px solid <divider colour>; margin-top: 1rem`.
+- Row: `display: flex; justify-content: space-between; align-items: center; gap: 0.5rem; margin-top: 0.5rem`.
+- Group: `display: flex; flex-direction: row; gap: 0.5rem`.
+- Secondary button: transparent background, no border, accent-coloured text, subtle tinted background on hover.
+- Primary button: accent-coloured fill, contrasting text, raised surface treatment, darker fill on hover.
+- Both buttons: `display: inline-flex; align-items: center; justify-content: center; border-radius: 4px; cursor: pointer`, with a transition on background colour.
+
+## Edge Cases & Special Logic
+
+- **Both arrays empty.** The parent already suppresses the component when there are no buttons at all, but the component must still tolerate empty or absent arrays and render nothing but its own container.
+- **One array empty.** Render the other group and leave the empty group's slot in place, so the remaining group keeps its edge alignment rather than sliding across the row.
+- **A single group with many entries.** Do not wrap, truncate, or collapse into an overflow menu. The runtime decides how many actions exist.
+- **Duplicate `name` values.** The `name` doubles as the entry's identity in the rendered list. If the runtime supplies duplicates, fall back to combining the name with its position so the two entries stay distinct.
+- **Missing `jsAction`.** Pass through whatever the entry carries. Do not substitute a default — a silently wrong action identifier is worse than a failed call the runtime can report.
+- **Rapid repeated activation.** The component does not debounce or disable. If the parent needs that, the parent applies it.
+
+## Dependencies
+
+- `PCore.getLocaleUtils().getLocaleValue(name, 'Assignment')` — resolves every button label.
+- The design system's button primitive, in two emphasis levels.
+- The design system's separator or divider primitive.
+
+No component registry lookups, no data page calls, no case info access.
+
+## Design System Mapping
+
+**UI control type:** An action bar — a divider followed by two opposed groups of buttons.
+
+- **Primary button** → the DS's filled, contained, or solid button variant
+- **Secondary button** → the DS's text, ghost, subtle, or tertiary variant
+- **Row** → the DS's button group, toolbar, or a flex container with space between the two groups
+- **Separator** → the DS's divider or separator component
+
+Use native button semantics so the row is reachable and operable by keyboard. Buttons carry no explicit role or label attributes beyond their localized text content — the text is the accessible name, which is another reason the label must be localized rather than rendered from the raw key.