@pega/sdk 0.0.4 → 0.0.6

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.

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

@@ -0,0 +1,178 @@
+# Skill: MultiStep
+
+Assignment step navigation. Renders the ordered steps of a multi-step assignment as a stepper, and hosts the current step's form content inside it.
+
+> **Prerequisite skill:** [`infra-components.md`](../infra-components.md) — covers architecture, the override contract, localization, and registration conventions common to ALL infrastructure components.
+
+---
+
+## Component Purpose
+
+Wraps the form content of a multi-step assignment with a progress indicator showing every step, which are done, which is active, and which are ahead. Unlike `Stages`, this is **assignment** chrome: it describes progress through the work item currently being completed, so it does render inside an embedded assignment.
+
+The runtime supplies the step model and the form content. This component decides only how to arrange them.
+
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> A stepper that only renders a row of labels is not this component. All of the following are part of the contract and are frequently dropped:
+>
+> - [ ] **Two layouts.** A vertical layout and a horizontal layout, selected by an input. Both must be implemented
+> - [ ] **Sub-steps.** A step may contain nested steps. When it does, the nested list renders and the form content goes inside the active nested step, not the parent
+> - [ ] **The active-step fallback.** When no step is marked active, a documented two-level fallback decides which one is
+> - [ ] **Child content placement.** The form content renders inside the active step only — never above the stepper, never in every step
+> - [ ] **Registry resolution.** The assignment card is resolved from the component registry, never imported
+> - [ ] **Unchanged forwarding.** The accessor, item key, button definitions and press callback pass through to the assignment card exactly as received
+
+## Pega Metadata
+
+- **Registration key:** `MultiStep` (in the project's component map)
+- **Category:** Infrastructure — case chrome, overridable
+- **Extends:** The project's base component interface
+- **Rendered by:** The SDK's assignment component, when the assignment has navigation steps
+- **Renders:** `AssignmentCard`, resolved from the component registry
+
+## Inputs
+
+| Prop                    | Type                                           | Required | Description                                                                            |
+| ----------------------- | ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
+| `getPConnect`           | `function`                                     | Yes      | PConnect getter                                                                        |
+| `children`              | renderable content                             | No       | The current step's form content, supplied by the runtime                               |
+| `itemKey`               | `string`                                       | Yes      | Work item identifier. Forwarded to the assignment card. Default empty string           |
+| `actionButtons`         | `any[]`                                        | Yes      | Action button definitions. Forwarded to the assignment card unchanged, not parsed here |
+| `onButtonPress`         | `(action: string, buttonType: string) => void` | Yes      | Action press callback. Forwarded to the assignment card                                |
+| `bIsVertical`           | `boolean`                                      | Yes      | Selects the vertical layout when true, the horizontal layout when false                |
+| `arNavigationSteps`     | `any[]`                                        | Yes      | The ordered step model                                                                 |
+| `arCurrentStepIndicies` | `number[]`                                     | No       | Supplied by the runtime but not used. Accept it; do not rely on it                     |
+
+Each navigation step entry carries:
+
+| Field            | Type     | Description                                                                              |
+| ---------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `name`           | `string` | The step label                                                                           |
+| `ID`             | `string` | The step identifier, used to match the active step                                       |
+| `actionID`       | `string` | A stable identifier suitable for identifying the step in a rendered list                 |
+| `visited_status` | `string` | The step's progress state — `'current'`, `'success'`, or a value meaning not yet reached |
+| `steps`          | `any[]`  | Optional nested sub-steps, each with the same shape                                      |
+
+## Implementation Structure
+
+**Module Setup:** The component depends on the design system's stepper primitives in both orientations, and on the project's component registry to resolve the assignment card. Define the input contract as an extension of the project's base component interface with the step model, the layout flag, the item key, the action button definitions, and the press callback.
+
+**Main Component Logic** — steps in order:
+
+1. Resolve `AssignmentCard` from the project's component registry. Do not import it.
+2. Receive `getPConnect`, `children`, `itemKey` (default empty string), `actionButtons`, `onButtonPress`, `bIsVertical`, and `arNavigationSteps` from inputs.
+3. Resolve the layout utilities from `PCore.getSDKUtils()`: `getVBodyClass`, `getAutoFlexClass`, and `isLastStep`. Record the total step count from the length of `arNavigationSteps`.
+4. Resolve the active step. Take the first entry whose `visited_status` is `'current'`. If there is none, take the **last** entry whose `visited_status` is `'success'`. If there is none of those either, take the first entry.
+5. Define a press handler that forwards its two arguments to `onButtonPress` unchanged.
+6. Branch on `bIsVertical` and render the corresponding layout, described below. Both layouts render the same step model and place the child content in the same place; only the arrangement differs.
+7. Wherever the child content is placed, render it inside the resolved assignment card, passing `getPConnect`, `itemKey`, `actionButtons` and the press handler, with the child content as the card's own content.
+
+### Vertical Layout
+
+Render a vertical stepper. For each step in order, keyed by its `actionID`, render a step block containing:
+
+- A header carrying the step's progress state, holding a circular indicator with the step's position number (one-based) and, when the step is active, its label
+- A body whose styling class comes from `getVBodyClass(index, totalSteps)`
+
+Inside the body: when the step has sub-steps, render them as a list — one item per sub-step, each keyed by its own identifier, showing a state indicator icon and the sub-step label, and hosting the assignment card when that sub-step is the active one. When the step has no sub-steps and is the active step, host the assignment card directly in the body.
+
+### Horizontal Layout
+
+Render a horizontal stepper in two parts.
+
+First, a header strip: for each step in order, keyed by its `actionID`, a header carrying the step's progress state, holding a circular indicator with the step's position number and the step's label when active. Between consecutive headers, render a connector line whose flex behaviour comes from `getAutoFlexClass(step, arNavigationSteps)`. Suppress the connector after the final step, determined by `isLastStep(index, totalSteps)`.
+
+Then, below the strip: for each step, when it has sub-steps, render them as a list with the same shape as the vertical layout; when it has no sub-steps and its `ID` matches the active step's `ID`, host the assignment card.
+
+## Behavioral Contract
+
+### Active Step Resolution
+
+Three levels, in order:
+
+1. The first step whose `visited_status` is `'current'`
+2. Otherwise, the **last** step whose `visited_status` is `'success'` — the furthest point reached, not the first
+3. Otherwise, the first step
+
+The fallback is not defensive padding. A step model with nothing marked current is a normal state, and skipping the fallback means the form content renders nowhere and the assignment appears blank.
+
+### Child Content Placement
+
+The child content is the current step's form. It renders **once**, inside the active step, wrapped by the assignment card. Rendering it outside the stepper, above it, or in every step are all wrong — the first two lose the association between the step and its form, the third renders the form repeatedly.
+
+When the active step has sub-steps, the content belongs to the active **sub**-step, not the parent step.
+
+### Assignment Card Delegation
+
+The assignment card is resolved from the project's component registry so that a customer's own override wins. It receives `getPConnect`, `itemKey`, `actionButtons` and the press callback, and the form content as its content.
+
+`actionButtons` is forwarded **as received**. This component does not split it into primary and secondary groups, does not localize button labels, and does not render buttons itself — the assignment card does all of that.
+
+### Step State
+
+Each step's `visited_status` drives its visual state: active, completed, or not yet reached. Apply the state to the step's header so the indicator and the label pick it up together. Step labels are shown for the active step; the position number identifies the others.
+
+### Sub-Steps
+
+A step's `steps` field is optional. When present, the parent step contributes only its header and the nested list — the form content belongs to whichever sub-step is active. When absent, the parent step itself may host the content. A step must never render both its own content and a sub-step list.
+
+## Visual Specifications
+
+| Element              | Description                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
+| Step indicator       | A circle containing the step's one-based position number                                            |
+| Active indicator     | Accent-coloured fill with contrasting text                                                          |
+| Completed indicator  | Completed-state fill with contrasting text                                                          |
+| Future indicator     | No fill, outlined, muted text                                                                       |
+| Step label           | Shown for the active step; truncated with an ellipsis rather than wrapped                           |
+| Vertical body        | Indented to align beneath the step label, with a connector line running through the indented gutter |
+| Horizontal connector | A line between consecutive step headers, absent after the final step                                |
+| Sub-step item        | An indicator icon and a label; the active sub-step is emphasized                                    |
+
+**CSS-only implementation notes (if implementing without design system stepper components):**
+
+- Step indicator: `border-radius: 50%; height: 24px; width: 24px; position: relative`, with the number centred inside it.
+- Step label: `display: inline-block; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 50px`.
+- Vertical stepper: `display: block; text-align: left`; each header `display: flex; align-items: center`; body indented by roughly the indicator width plus its gutter.
+- Vertical connector: a left border drawn on the indented body, extending above and below it so consecutive steps join.
+- Horizontal header strip: `display: flex; align-items: center; white-space: nowrap`; connectors flex to fill the space between headers.
+- Sub-step list: `list-style: none`, indented from the parent step, with spacing between items.
+- Active sub-step label: bold, full-strength text; inactive sub-step label: muted.
+
+The active, completed and not-yet-reached states must be distinguishable by more than colour alone.
+
+## Edge Cases & Special Logic
+
+- **No step marked current.** Covered by the fallback. Do not render a blank assignment.
+- **Every step marked complete.** The fallback selects the last successful step, which is correct — the assignment is finished but still displayed.
+- **A single step.** Render the stepper with one entry and no connectors. Some assignments legitimately have one navigation step.
+- **Sub-steps present but none active.** The parent step contributes its header and nested list, and no content renders beneath it. Do not fall back to hosting the content on the parent.
+- **`arCurrentStepIndicies` supplied.** Accept it as an input for contract compatibility, but derive nothing from it. The active step comes from the resolution above.
+- **Missing `actionID`.** It is the identity used for the rendered step list. If it is absent, fall back to the step's `ID`, then to its position, so repeated steps stay distinct as the model updates.
+- **Long step labels.** Labels truncate with an ellipsis rather than wrapping, so the horizontal strip keeps a single line.
+- **Many steps in the horizontal layout.** The strip does not wrap. Let the connectors absorb the available space and allow the strip to be scrollable if the design system supports it, rather than reflowing into multiple rows.
+- **Absent child content.** The runtime may render the stepper before content is available. Render the stepper and the assignment card without content; do not suppress the stepper.
+
+## Dependencies
+
+- The project's component registry, resolving `AssignmentCard` — hosts the form content and the action buttons.
+- `PCore.getSDKUtils().getVBodyClass(index, totalSteps)` — the styling class for a vertical step's body, which decides whether the connector continues past it.
+- `PCore.getSDKUtils().getAutoFlexClass(step, arNavigationSteps)` — the flex behaviour of a horizontal connector, which decides how the strip distributes space.
+- `PCore.getSDKUtils().isLastStep(index, totalSteps)` — whether the connector after a horizontal step is suppressed.
+- The design system's stepper primitives, in both orientations.
+
+## Design System Mapping
+
+**UI control type:** A stepper with two orientations, hosting content inside the active step.
+
+- **Vertical layout** → the DS's vertical stepper, or a list of step blocks with an indented body per step
+- **Horizontal layout** → the DS's horizontal stepper, with a header strip and content below
+- **Step indicator** → the DS's step icon or numbered badge, using its completed / active / pending states
+- **Connector** → the DS's step connector, or a flexible rule between headers
+- **Sub-step list** → a nested list; most design systems have no nested-step primitive, so build it from list and icon primitives
+- **Content host** → always the registry-resolved assignment card, never the DS's own step content slot rendering the children directly
+
+If the design system's stepper is interactive, disable step selection. Steps are advanced by the runtime through the action buttons, not by clicking the stepper.
+
+Mark the active step so assistive technology can announce it, give each step's position number a textual equivalent, and hide decorative connectors and state icons from assistive technology. Sub-step labels are text, not form labels — do not bind them to controls.

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

@@ -0,0 +1,140 @@
+# Skill: Stages
+
+Case stage progress indicator. Renders the case's lifecycle stages as a horizontal progression, marking which are complete, which is current, and which are still ahead.
+
+> **Prerequisite skill:** [`infra-components.md`](../infra-components.md) — covers architecture, the override contract, localization, and registration conventions common to ALL infrastructure components.
+
+---
+
+## Component Purpose
+
+Shows where a case sits in its lifecycle. It is display-only: it has no callbacks, triggers no actions, and is not interactive. Stages are not selectable — the runtime advances the case, not the user.
+
+> ⚠️ **CRITICAL — THIS IS CASE CHROME, NOT ASSIGNMENT CHROME**
+>
+> `Stages` renders as a named region of the **case view**. It is a property of the case, not of the assignment being worked. It therefore does **not** appear inside an embedded assignment, and must never be wired into one.
+>
+> If an embedded flow is showing a stage indicator, the flow launched the full case view instead of the assignment — fix the case-creation call, do not add this component. If a component list for an embedded flow includes `Stages`, question the list rather than generating it. Generate this component for a portal or full case view experience only.
+
+## Pega Metadata
+
+- **Registration key:** `Stages` (in the project's component map)
+- **Category:** Infrastructure — case chrome, overridable
+- **Extends:** The project's base component interface
+- **Rendered by:** The case view template, as the `stages` named region
+
+## Inputs
+
+| Prop          | Type       | Required | Description                                                                        |
+| ------------- | ---------- | -------- | ---------------------------------------------------------------------------------- |
+| `getPConnect` | `function` | Yes      | PConnect getter                                                                    |
+| `stages`      | `any[]`    | Yes      | The raw, unfiltered stage list from the runtime. Must be filtered before rendering |
+
+Each raw stage entry carries at least:
+
+| Field            | Type     | Description                                                                |
+| ---------------- | -------- | -------------------------------------------------------------------------- |
+| `name`           | `string` | The stage label **key**, to be localized before display                    |
+| `ID` or `id`     | `string` | The stage identifier. **Either casing may be present** — accept both       |
+| `visited_status` | `string` | The stage's progress state. The value `'completed'` marks a finished stage |
+
+## Implementation Structure
+
+**Module Setup:** The component depends on the design system's breadcrumb, step, or list primitives and an indicator icon for completed stages. Define the input contract as an extension of the project's base component interface with a `stages` field.
+
+**Main Component Logic** — steps in order:
+
+1. Receive `getPConnect` and `stages` from inputs; call `getPConnect()` into `pConn`. Resolve the localization service via `pConn.getLocalizationService()`.
+2. Filter the raw list through `PCore.getSDKUtils().getFilteredStages(stages)`. The runtime supplies every stage including ones that must not be shown; this utility decides what is displayable. Render the filtered list, never the raw input.
+3. Read the active stage identifier from case info: `pConn.getValue(PCore.getConstants().CASE_INFO.STAGEID, '')`. Use the runtime constant, not a literal property name, and supply an empty string as the fallback.
+4. Derive a display model from the filtered list — one entry per stage, carrying: the localized `name`; the identifier resolved as `ID` or `id`, whichever is present; a `complete` flag set when `visited_status` equals `'completed'`; a `current` flag set when the identifier matches the active stage identifier; and a `last` flag set when the entry is the final one in the filtered list.
+5. Render the derived model as a labelled navigation landmark containing an ordered list. Between consecutive entries, render a decorative separator hidden from assistive technology.
+6. Render each entry's label with the visual treatment its state calls for, and render a completion indicator ahead of the label for completed entries.
+
+## Behavioral Contract
+
+### Stage Filtering
+
+Always filter through `PCore.getSDKUtils().getFilteredStages(stages)` before doing anything else. Deriving state from, counting, or rendering the raw `stages` input produces stages the case is not meant to show, and makes the `last` flag wrong.
+
+### Current Stage Resolution
+
+The current stage is determined by comparing each stage's identifier against the case's active stage identifier read from case info. It is **not** derived from `visited_status`. A stage may carry a status that suggests it is in progress while the case has already moved on; case info is authoritative.
+
+### Identifier Casing
+
+Stage entries may expose their identifier as `ID` or as `id` depending on the source. Resolve it as the first of the two that is present. Reading only one casing silently breaks current-stage matching for the other.
+
+### State Precedence
+
+A stage is exactly one of three states, resolved in this order:
+
+1. **Current** — the identifier matches the active stage identifier
+2. **Completed** — not current, and `visited_status` equals `'completed'`
+3. **Future** — everything else
+
+**Current wins over completed.** A stage that is both marked completed and currently active renders as current. Testing `complete` first is the common mistake and makes the active stage look finished.
+
+### Localization
+
+Each stage label is resolved through `pConn.getLocalizationService().getLocalizedText(name)`. The `name` field is a key, not display text.
+
+### Display Only
+
+The component reads state and renders. It has no callbacks, no click handlers, and never writes to the store. Stages must not be selectable, focusable as controls, or navigable — the user cannot move a case by clicking its stage indicator.
+
+## Visual Specifications
+
+| Element              | Description                                                          |
+| -------------------- | -------------------------------------------------------------------- |
+| Container            | A raised surface with a light background, holding the progression    |
+| Progression          | A horizontal list that wraps when it exceeds the available width     |
+| Separator            | A directional indicator between consecutive stages, decorative only  |
+| Completed label      | Neutral, full-strength text, preceded by a completion indicator      |
+| Current label        | Accent-coloured and emphasized, visually the most prominent entry    |
+| Future label         | Muted, lower-contrast text                                           |
+| Completion indicator | A small check-style icon rendered before completed stage labels only |
+
+The three states must be distinguishable by more than colour alone — weight, an icon, or both — so the progression is readable without colour perception.
+
+**CSS-only implementation notes (if implementing without design system step components):**
+
+- Container: `padding: 8px 16px; border-radius: 4px; background: <surface colour>` with a subtle raised shadow.
+- Progression: `display: flex; flex-wrap: wrap; align-items: center; gap: 4px; list-style: none; padding: 0; margin: 0`.
+- Each list item: `display: flex; align-items: center`.
+- Separator: muted colour, icon sized around `20px`, filled with the current text colour.
+- Completed label: full-strength body colour, normal weight.
+- Current label: accent colour, `font-weight: 600`.
+- Future label: muted colour, normal weight.
+- Completion indicator: `display: inline-flex; align-items: center; margin-right: 4px`, icon sized around `18px`.
+
+## Edge Cases & Special Logic
+
+- **Empty stage list.** If filtering yields nothing, render nothing rather than an empty container with padding and a shadow.
+- **Single stage.** Render the one entry with no separators. The `last` flag is true for it.
+- **No matching current stage.** If the active stage identifier is empty or matches nothing in the filtered list, no entry is current. Every entry falls through to completed or future; do not force the first or last entry to be current.
+- **Long stage names.** Names come from the case type and can be long. The progression wraps; it does not truncate or scroll horizontally, so a long name must not force the container to overflow.
+- **Raw list longer than the filtered list.** Expected and normal. All indexing, counting, and the `last` flag operate on the filtered list.
+- **Repeated stage names.** Stage names are not unique — identity comes from the identifier and the position, not the label.
+
+## Dependencies
+
+- `PCore.getSDKUtils().getFilteredStages(stages)` — reduces the raw list to the displayable stages.
+- `PCore.getConstants().CASE_INFO.STAGEID` — the case info key for the active stage identifier.
+- `pConn.getValue(key, fallback)` — reads the active stage identifier from case info.
+- `pConn.getLocalizationService().getLocalizedText(name)` — localizes each stage label.
+- The design system's breadcrumb, step, or inline list primitive, plus a completion icon.
+
+## Design System Mapping
+
+**UI control type:** A non-interactive horizontal progression — a breadcrumb trail or a read-only stepper.
+
+- **Progression** → the DS's breadcrumb or stepper component, in its non-interactive form
+- **Stage entry** → a breadcrumb item or step label
+- **Separator** → the DS's breadcrumb separator, or a directional icon
+- **Completion indicator** → the DS's check or success icon
+- **Container** → the DS's card, surface, or panel primitive
+
+If the design system's stepper is interactive by default, disable its interactivity rather than leaving stages clickable. If it renders its own numbering, prefer the completion indicator over numbers — stages are named lifecycle phases, not numbered steps.
+
+Use an ordered list inside a labelled navigation landmark so the progression is announced as a sequence. Mark separators as decorative and hide them from assistive technology; they carry no meaning beyond the ordering the list already conveys.