@pega/sdk 0.0.5 → 0.0.6

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.