@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/template-skills/DetailsThreeColumn.md

@@ -0,0 +1,85 @@
+# Skill: DetailsThreeColumn
+
+Read-only three-column details template. Renders child fields in DISPLAY_ONLY mode in a 3-column grid inside a FieldGroup, with optional highlighted data.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Identical to `Details` and `DetailsTwoColumn` in all behavior except children are distributed into a **three-column grid** (one-third width per child). Used in wide details regions where the design calls for three equal columns of fields.
+
+> The implementation is nearly identical to `Details`. See `Details.md` for full pattern descriptions. Only the column width differs.
+
+## Pega Metadata
+
+- **Registration key:** `DetailsThreeColumn` (in the project's component map)
+- **Category:** Display template
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Name                  | Type       | Required | Description                                                          |
+| --------------------- | ---------- | -------- | -------------------------------------------------------------------- |
+| `label`               | `string`   | Yes      | Section heading for the FieldGroup wrapper                           |
+| `showLabel`           | `boolean`  | No       | Whether to show the section label. Default `true`                    |
+| `showHighlightedData` | `boolean`  | No       | Whether to render highlighted fields above children. Default `false` |
+| `getPConnect`         | `function` | Yes      | PConnect getter                                                      |
+
+## Implementation Structure
+
+**Module Setup:** Obtain the FieldGroup component from the project's component registry. Access the project's bridge component for rendering child configuration objects as live components.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `label`, `showLabel` (default `true`), `showHighlightedData` (default `false`), and `getPConnect`.
+2. Merge inherited display settings: `propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() }`.
+3. Set display mode on the PConnect instance: `getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `getPConnect().setInheritedProp('readOnly', true)`.
+4. Re-create children from `getPConnect().getChildren()` — map each config object into a live component via the bridge component, passing a unique key per child.
+5. If `showHighlightedData` is true, retrieve `highlightedData` from `getPConnect().getRawMetadata().config`, set each field's `displayMode` to `'STACKED_LARGE_VAL'`, mark any field whose value is `'@P .pyStatusWork'` with `type: 'TextInput'` and `displayAsStatus: true`, then call `getPConnect().createComponent(field, '', 0, {})` for each.
+6. Render: FieldGroup wrapper (showing `propsToUse.label` if `propsToUse.showLabel` is true), optional highlighted data row (3-column grid with bottom padding), then all children in a 3-column grid.
+
+## Behavioral Contract
+
+All steps identical to `Details`, except:
+
+- **Regular children grid:** Each child renders at one-third width (three per row).
+- **Highlighted data grid:** Each highlighted field also renders at one-third width.
+- All other behaviors (inherited settings merge, `setInheritedProp('displayMode', 'DISPLAY_ONLY')`, `setInheritedProp('readOnly', true)`, FieldGroup wrapper, pyStatusWork handling) are identical to `Details`.
+
+## Visual Specifications
+
+### Column Structure
+
+|                         | Details    | DetailsTwoColumn | DetailsThreeColumn |
+| ----------------------- | ---------- | ---------------- | ------------------ |
+| Column width per child  | full-width | 1/2              | **1/3**            |
+| Columns per row         | 1          | 2                | **3**              |
+| Highlighted data column | full-width | 1/2              | **1/3**            |
+
+**CSS-only implementation notes:**
+
+- Children grid: `display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 8px`.
+- Highlighted data row: `display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 8px; padding-bottom: 1rem`.
+- Wrap in FieldGroup (see `FieldGroup.md` DSE skill).
+
+## Edge Cases & Special Logic
+
+All edge cases identical to `Details`. See `Details.md`.
+
+## Dependencies
+
+- The project's component registry — to resolve the `FieldGroup` component at runtime
+- A bridge component for rendering PConnect child configuration objects as live components
+
+## Design System Mapping
+
+**UI control type:** Read-only labeled section with fields in a three-column grid.
+
+When implementing in a specific design system, map the following:
+
+- 3-column layout — each field takes one-third of the available width
+- Grid container with spacing/gap between items
+- FieldGroup wrapper component for the labeled section (see `FieldGroup.md` DSE skill)
+- All other behaviors inherited from `Details` (DISPLAY_ONLY, readOnly, FieldGroup, highlighted data)

package/templates/react-sdk-reference/.ai-common/skills/template-skills/DetailsTwoColumn.md

@@ -0,0 +1,77 @@
+# Skill: DetailsTwoColumn
+
+Read-only two-column details template. Renders child fields in DISPLAY_ONLY mode in a 2-column grid inside a FieldGroup, with optional highlighted data.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Identical to `Details` in all behavior except children are distributed into a **two-column grid** (half width per child) instead of single-column. Used in details regions where the design calls for side-by-side field pairs.
+
+> The implementation is nearly identical to `Details`. See `Details.md` for full pattern descriptions. Only the column width differs.
+
+## Pega Metadata
+
+- **Registration key:** `DetailsTwoColumn` (in the project's component map)
+- **Category:** Display template
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input                 | Type       | Required | Description                                                          |
+| --------------------- | ---------- | -------- | -------------------------------------------------------------------- |
+| `label`               | `string`   | Yes      | Section heading for the FieldGroup wrapper                           |
+| `showLabel`           | `boolean`  | No       | Whether to show the section label. Default `true`                    |
+| `showHighlightedData` | `boolean`  | No       | Whether to render highlighted fields above children. Default `false` |
+| `getPConnect`         | `function` | Yes      | PConnect getter                                                      |
+
+## Implementation Structure
+
+Identical to the `Details` implementation structure except grid items use half width (two columns) instead of full width. Both the highlighted-data grid items and the regular-children grid items render at half width (two per row). See `Details.md`'s Implementation Structure for the full pattern description — the ONLY change is full-width → half-width per child.
+
+## Behavioral Contract
+
+All steps identical to `Details`, except:
+
+- **Regular children grid:** Each child renders at half width (two per row, side by side).
+- **Highlighted data grid:** Each highlighted field also renders at half width.
+- All other behaviors (inherited inputs merge, `setInheritedProp('displayMode', 'DISPLAY_ONLY')`, `setInheritedProp('readOnly', true)`, FieldGroup wrapper, pyStatusWork handling) are identical to `Details`.
+
+## Visual Specifications
+
+### Column Structure
+
+|                         | Details    | DetailsTwoColumn |
+| ----------------------- | ---------- | ---------------- |
+| Column width per child  | Full width | **Half width**   |
+| Columns per row         | 1          | **2**            |
+| Highlighted data column | Full width | **Half width**   |
+
+**CSS-only implementation notes:**
+
+- Children grid: two equal columns with ~8px gap between items.
+- Highlighted data row: two equal columns with ~8px gap and ~1rem bottom padding.
+- Wrap in FieldGroup (see `FieldGroup.md` DSE skill).
+
+## Edge Cases & Special Logic
+
+All edge cases identical to `Details`. See `Details.md`.
+
+## Dependencies
+
+- The project's PConnect bridge utility (for rendering child PConnect nodes)
+- The project's component registry (to retrieve `FieldGroup`)
+
+## Design System Mapping
+
+**UI control type:** Read-only labeled section with fields in a two-column grid.
+
+When implementing in a specific design system, map the following:
+
+- The outer wrapper is a labeled group container (same as Details — fieldset/legend, card, or boxed section). Use whatever grouped-section primitive your design system provides.
+- Each child occupies half the container width (two columns per row). Use your design system's grid or multi-column layout primitive with two equal columns and ~8px spacing between items.
+- Highlighted data renders in the same two-column layout with additional bottom padding (~1rem) separating it from regular children.
+- 2-column layout — each field takes half the available width.
+- All other behaviors inherited from `Details` (DISPLAY_ONLY, readOnly, FieldGroup, highlighted data).

package/templates/react-sdk-reference/.ai-common/skills/template-skills/DynamicTabs.md

@@ -0,0 +1,103 @@
+# Skill: DynamicTabs
+
+Data-driven tab template. Renders tabs dynamically from a `referenceList` data source — one tab per row in the list, with tab labels derived from a configurable property.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Unlike `SubTabs` or `DetailsSubTabs` where tabs are defined statically in metadata, `DynamicTabs` generates tabs at runtime from a reference list. The number and labels of tabs depend on the data in the reference list. Each tab's content is built via `buildView`.
+
+## Pega Metadata
+
+- **Registration key:** `DynamicTabs` (in the project's component map)
+- **Category:** Navigation template — data-driven
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input           | Type       | Required | Description                                               |
+| --------------- | ---------- | -------- | --------------------------------------------------------- |
+| `referenceList` | `string`   | Yes      | Property path to the reference list (e.g. `'.pxResults'`) |
+| `getPConnect`   | `function` | Yes      | PConnect getter                                           |
+
+## Implementation Structure
+
+**Module Setup:** This component requires the `buildView` helper (from the project's field-group utilities) and the project's base component interface. Define a component input contract extending the base component interface with `showLabel: boolean`, `label: string`, and optional `referenceList?: any[]`.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `referenceList`, `showLabel`, `label`, and `getPConnect`; call `getPConnect()` once into `pConnect`; merge inherited inputs into `inputsToUse = { label, showLabel, ...pConnect.getInheritedProps() }`.
+2. **Resolve tab label property:** read `tablabel` from `pConnect.getComponentConfig()`, then resolve it to a raw property path via `PCore.getAnnotationUtils().getPropertyName(tablabel)` into `tablabelProp`.
+3. **Get reference list data:** `referenceListData = pConnect.getValue(referenceList + '.pxResults', '')`.
+4. **Memoized tab views** (recomputed only when `referenceListData` changes): force display-only mode via `pConnect.setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `pConnect.setInheritedProp('readOnly', true)`; then, if `referenceListData` is present, map each row to a keyed fragment (keyed by `item[tablabelProp]`) wrapping `buildView(pConnect, index, '')`, and normalize the result to an array.
+5. Declare local state `panelShown` (number, default `0`) with a click handler that parses the clicked tab's id as an integer and updates the state.
+6. **Build tab items:** map `referenceListData` to `{ name, id }` objects, where `name` is `item[tablabelProp]` or, if missing, the localized fallback `PCore.getLocaleUtils().getLocaleValue('No label specified in config', 'Generic')`, and `id` is the row index; default to an empty array when there's no data.
+7. Render: an optional heading element (shown when `inputsToUse.label` is set); a tab context (value = `panelShown` as a string) wrapping a scrollable tab bar with auto scroll buttons (one tab item per `tabItems` entry, labeled `tab.name`, valued `tab.id`) and one tab panel per `tabItems` entry (keyed and valued by `tab.id`, `tabIndex` set to the numeric id) showing `memoisedTabViews?.[tab.id]` or a "No content exists" fallback.
+
+## Behavioral Contract
+
+### Tab Label Resolution
+
+1. Get component config: `tablabel = getPConnect().getComponentConfig().tablabel`.
+2. Get property name: `tablabelProp = PCore.getAnnotationUtils().getPropertyName(tablabel)`.
+3. For each row `i` in `referenceListData`:
+   - Tab label = `pConnect.getValue(referenceList + '[' + i + '].' + tablabelProp)`.
+
+### Reference List Data
+
+`referenceListData` is obtained via `pConnect.getValue(referenceList + '.pxResults')` and returns an array of row objects.
+
+### Tab Views
+
+For each row index `i`, the tab view is `buildView(pConnect, i, '')`. Memoized computation — recalculate only when `referenceListData` changes.
+
+### State
+
+- `currentPanel`: index of active tab (number, default `0`) — managed as local state.
+- `changePanel(index)`: updates the local state to the new index.
+
+### Render
+
+- A tab context wrapper with value = `currentPanel` as a string.
+- A scrollable tab bar — one tab item per row, labeled with the resolved tab label and valued with the row index as a string.
+- One tab panel per row containing `tabView[i]`.
+
+## Visual Specifications
+
+Identical tab bar appearance to `SubTabs`.
+
+**CSS-only implementation notes:**
+
+- Same tab bar and panel styles as `SubTabs.md`.
+- Tab count is dynamic — do not hard-code tab widths.
+
+## Edge Cases & Special Logic
+
+- `referenceListData` may be undefined on first render — default to empty array, render no tabs.
+- `tablabel` may be a reference annotation like `@[FIELD/.pyLabel]` — `PCore.getAnnotationUtils().getPropertyName()` resolves it to the raw field path.
+- `buildView` is wrapped in a memoized computation keyed on `referenceListData` — if the list changes, tab views must be regenerated.
+- `changePanel` receives the raw index (number) but the tab context value is a string — always convert the index to a string.
+- Empty reference list — show a "No items" empty state instead of an empty tab bar.
+
+## Dependencies
+
+- `buildView` from the project's field-group utilities — generates the content view for each tab
+- `PCore.getAnnotationUtils().getPropertyName()` — resolves annotation to property path
+- `PCore.getLocaleUtils().getLocaleValue()` — provides localized fallback label
+- A tab component from your chosen design system — for rendering the tab bar and panels
+
+## Design System Mapping
+
+**UI control type:** Data-driven tab navigation — tab count and labels from a reference list.
+
+When implementing in a specific design system, map the following:
+
+- A tab context/container that tracks the active panel by string value
+- A scrollable tab bar with auto scroll buttons, rendering one tab per data row
+- A tab panel container that shows the content for the active tab
+- `tablabelProp` resolution via `PCore.getAnnotationUtils().getPropertyName()` is required — do not hardcode the label field
+- `buildView(pConnect, rowIndex, '')` generates the content for each tab — the empty string third arg means no specific child config lookup
+- Tab count is entirely data-driven — handle 0, 1, and many tab cases

package/templates/react-sdk-reference/.ai-common/skills/template-skills/FieldGroupTemplate.md

@@ -0,0 +1,130 @@
+# Skill: FieldGroupTemplate
+
+Repeating field group template. Renders a list of field group rows from a reference list, supporting add/delete row actions and a read-only display mode.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+> ⚠️ **CRITICAL — DO NOT SIMPLIFY THIS COMPONENT**
+>
+> This template manages a repeating list of field groups with add/delete actions. It MUST NOT be reduced to a simple delegation to `FieldGroup` or `FieldGroupList`. The following are MANDATORY:
+>
+> 1. `getReferenceList(pConn)` from the project's field-group utility helpers — resolves the reference list path
+> 2. `buildView(pConn, index, lookForChildInConfig)` from the project's field-group utility helpers — builds each row's view
+> 3. `pConn.setReferenceList(resolvedList)` — sets the reference list on PConnect
+> 4. `pConn.getListActions().initDefaultPageInstructions(resolvedList)` — initializes list instructions
+> 5. A synchronous layout effect for list initialization (must run before paint, not a standard lifecycle effect)
+> 6. Add/delete record handlers using `pConn.getListActions().insert()` and `.deleteEntry()`
+> 7. A memoized computation for `MemoisedChildren` built from referenceList iteration plus `buildView`
+> 8. `allowActions` handling (allowAdd, allowDelete)
+> 9. `isReadonlyMode` check switching between FieldGroupList (edit) and FieldGroup (read-only)
+>
+> **Minimum Implementation Checklist:**
+>
+> - [ ] `getReferenceList` and `buildView` sourced from the project's field-group utility helpers
+> - [ ] `pConn.getListActions()` used for insert/delete
+> - [ ] Synchronous layout effect for `initDefaultPageInstructions`
+> - [ ] `addRecord` and `deleteFieldGroupItem` handlers
+> - [ ] Edit mode renders a FieldGroupList with items, onAdd, and onDelete
+> - [ ] Read-only mode renders FieldGroup instances with `buildView` children
+> - [ ] `allowActions` / `allowTableEdit` inputs respected
+
+---
+
+## Component Purpose
+
+Renders a repeating list of field group rows sourced from a PConnect reference list. In edit mode, rows can be added and deleted via list actions. In read-only mode (DISPLAY_ONLY), delegates to a read-only FieldGroup renderer. Each row is built via `buildView`.
+
+## Pega Metadata
+
+- **Registration key:** `FieldGroupTemplate` (in the project's component map)
+- **Category:** Form template — repeating
+
+## Inputs
+
+| Input            | Type       | Required | Description                                                      |
+| ---------------- | ---------- | -------- | ---------------------------------------------------------------- |
+| `label`          | `string`   | Yes      | Section heading                                                  |
+| `showLabel`      | `boolean`  | No       | Whether to show the heading. Default `true`                      |
+| `fieldHeader`    | `string`   | No       | Property ref for the dynamic row heading. E.g. `'.pyStatusWork'` |
+| `allowTableEdit` | `boolean`  | No       | Whether to show add/delete row controls. Default `true`          |
+| `displayMode`    | `string`   | No       | `'DISPLAY_ONLY'` triggers read-only rendering                    |
+| `readOnly`       | `boolean`  | No       | Alternative read-only flag                                       |
+| `getPConnect`    | `function` | Yes      | PConnect getter                                                  |
+
+Additional inputs accepted: `referenceList` (array, defaults to empty), `contextClass` (string, required), `renderMode` (string, optional), `heading` (string, defaults to empty), `lookForChildInConfig` (boolean, optional), `allowActions` (object, optional).
+
+## Main Component Logic
+
+Steps in order:
+
+1. Retrieve FieldGroup and FieldGroupList from the project's component registry.
+2. Receive inputs: `referenceList` (default empty array), `renderMode`, `contextClass`, `getPConnect`, `lookForChildInConfig`, `heading` (default empty string), `displayMode`, `fieldHeader`, `allowActions`, and `allowTableEdit` (alias `allowAddEdit`).
+3. Call `getPConnect()` into `pConn`. Resolve the reference list path via `getReferenceList(pConn)` into `resolvedList` and register it via `pConn.setReferenceList(resolvedList)`. Build `pageReference` by concatenating `pConn.getPageReference()` with `resolvedList`. Determine `isReadonlyMode` when `renderMode === 'ReadOnly'` or `displayMode === 'DISPLAY_ONLY'`. Default `HEADING` to `heading` or `'Row'`.
+4. **Resolve add/delete permissions:** check whether `allowActions` has any keys (`hasAllowActions`). Destructure `allowAdd`/`allowDelete` from it as `actionAdd`/`actionDelete`. Compute final `allowAdd`/`allowDelete` flags — when `hasAllowActions` is true, use `actionAdd ?? true` / `actionDelete ?? true`; otherwise fall back to `allowAddEdit ?? true` for both.
+5. **Init page instructions on mount** (edit mode only): inside a synchronous layout effect (must run before paint) keyed on `referenceList` length, when not in read-only mode, call `pConn.getListActions().initDefaultPageInstructions(resolvedList)`. This MUST be a synchronous layout effect, not a standard lifecycle effect, to avoid visual flicker during list initialization.
+6. Define `getDynamicHeaderProp(item, index)`: if `fieldHeader === 'propertyRef'` and `heading` resolves a value on `item` (via `item[heading.substring(1)]`), return that value; otherwise return a default label like "Row N".
+7. Define `addRecord`: if `PCore.getPCoreVersion()` includes `'8.7'`, call `pConn.getListActions().insert({ classID: contextClass }, referenceList.length, pageReference)`; otherwise call `pConn.getListActions().insert({}, referenceList.length)`. Define `deleteRecord(index)` similarly, calling `pConn.getListActions().deleteEntry(index, pageReference)` on 8.7 or `pConn.getListActions().deleteEntry(index)` otherwise.
+8. **Edit mode:** if not read-only, auto-add a first row when `referenceList` is empty and `allowAdd` is true. Produce a memoized computation (keyed on `referenceList` length) by mapping `referenceList` to objects of shape `{ id: index, name: <dynamic or default heading>, children: buildView(pConn, index, lookForChildInConfig) }`. Render FieldGroupList with `items`, `onAdd` (when `allowAdd` is true), and `onDelete` (when `allowDelete` is true).
+9. **Read-only mode:** force `pConn.setInheritedProp('displayMode', 'DISPLAY_ONLY')`. Produce a memoized computation (run once) by mapping `referenceList` to one FieldGroup per row (keyed by `item[heading]` or a fallback row key, named via the dynamic/default heading) containing `buildView(pConn, index, lookForChildInConfig)`. Render the list inside a wrapping container.
+
+## Behavioral Contract
+
+### Read-Only Mode
+
+If `displayMode === 'DISPLAY_ONLY'` or `readOnly === true`:
+
+1. Call `pConn.setInheritedProp('displayMode', 'DISPLAY_ONLY')`.
+2. Render a FieldGroup (from the component registry) per row — the design system component that shows data in a read-only layout.
+
+### Edit Mode
+
+1. **Get reference list:** `resolvedList = getReferenceList(pConn)` — extracts the reference list path string.
+2. **Set reference list:** `pConn.setReferenceList(resolvedList)` — ensures the pConn has the resolved list registered.
+3. **Build row views:** For each row index `i`, call `buildView(pConn, i, lookForChildInConfig)` to get the PConnect view for that row.
+4. **Render FieldGroupList** — the design system component for edit mode, receiving:
+   - Memoized items array for row content
+   - `onAdd`: calls `pConn.getListActions().insert(...)` with version-appropriate arguments
+   - `onDelete(index)`: calls `pConn.getListActions().deleteEntry(...)` with version-appropriate arguments
+   - Row headings: dynamic (from `fieldHeader` property ref) or default ("Row N")
+
+### `allowActions` Override
+
+If the field group is inside a read-only context (parent has set `readOnly` or `DISPLAY_ONLY`), `allowActions` is forced to `false` regardless of `allowTableEdit`.
+
+## Visual Specifications
+
+### Edit Mode
+
+- Section heading (`label`) at top (if `showLabel`).
+- List of row sections, each with:
+  - Dynamic heading from `fieldHeader` property value (e.g. `"Active"`, `"Pending"`).
+  - Row fields in a grid layout.
+  - Delete button (trash icon) per row.
+- Add row button at the bottom (e.g. "+ Add row").
+
+### Read-Only Mode
+
+- Section heading at top (if `showLabel`).
+- Flat list of rows — no add/delete controls.
+
+Use companion styles to achieve row cards with a border, border-radius, padding, and bottom margin. The add button appears as a text-style button below the last row. The delete button appears as an icon button at the top-right of each row section.
+
+## Edge Cases & Special Logic
+
+- `getReferenceList(pConn)` returns `undefined` if the reference list is not yet loaded — guard and render empty list.
+- `buildView(pConn, index, true)` — third argument `lookForChildInConfig=true` — required for embedded field groups.
+- Row index must be passed to `deleteEntry` as a number (not string).
+- `fieldHeader` is a property ref like `'.pyStatusWork'` — evaluate it per-row via `item[heading.substring(1)]` to get the display label for each row heading.
+- FieldGroupList and FieldGroup are design system extension components registered in the project's component registry.
+
+## Dependencies
+
+- `getReferenceList`, `buildView` from the project's field-group utility helpers
+- The project's component registry to retrieve FieldGroupList (edit mode) and FieldGroup (read-only mode)
+- The project's base component interface for rendering child PConnect views inside `buildView`
+
+## Design System Mapping
+
+Use repeating row cards for the edit mode layout. Each row should be a bordered card containing the fields generated by `buildView`. Provide an add button (text style) below the last row and a delete button (icon style) at the top-right of each row card. The design system's grouping or card primitive is the natural fit for each row. In read-only mode, use a simpler flat list of labelled groups without action controls. Hide add/delete controls when `allowActions` is false. The row heading is dynamic — evaluate the `fieldHeader` property ref per row.

package/templates/react-sdk-reference/.ai-common/skills/template-skills/HierarchicalForm.md

@@ -0,0 +1,200 @@
+# Skill: HierarchicalForm
+
+Multi-step tabbed form template. Renders form sections as horizontal tabs with per-tab validation error badges and persisted active tab navigation.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Renders a multi-step form where each section is a tab. Tabs display error badges when their content has validation errors. The active tab index is persisted to navigation state so it survives renders. Optional instruction HTML is displayed above the tab bar.
+
+## Pega Metadata
+
+- **Registration key:** `HierarchicalForm` (in the project's component map)
+- **Category:** Form template
+- **Extends:** the project's base component interface
+
+## Inputs
+
+| Input                | Type               | Required | Description                                                                                       |
+| -------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `children`           | child element list | Yes      | One child per tab section                                                                         |
+| `instructions`       | string             | No       | HTML instruction text shown above the tab bar                                                     |
+| `getPConnect`        | function           | Yes      | PConnect getter                                                                                   |
+| `tabsVisibility`     | object             | No       | Record mapping tab index to boolean visibility                                                    |
+| `template`           | string             | No       | Template identifier passed to deferred tab loading                                                |
+| `lastUpdateCaseTime` | string or number   | No       | Timestamp of last case update (falls back to `getPConnect().getValue('caseInfo.lastUpdateTime')`) |
+
+## Implementation Structure
+
+**Module Setup:** This component needs the project's base component interface for typing. The tab logic is encapsulated in a separate composable/helper module that handles active-tab persistence, tab-click handling, per-tab error counting, instructions extraction, and tab processing. Additionally, tab utility helpers (`getActiveTabId`, `getFirstVisibleTabId`, `tabClick`) and an instructions helper (`getInstructions`) are needed from the project's shared template utilities.
+
+**Main Component Logic** — steps in order:
+
+1. Invoke the extracted tab-logic composable, passing the component's inputs. It returns `currentTabId`, `handleTabClick`, `processedTabs`, and `instructions`.
+2. Guard: if there is no `currentTabId` (no visible tabs), render nothing.
+3. Render a flex column containing (if present) the instructions HTML rendered as raw HTML content, followed by a tab context wrapping a scrollable tab bar and tab panels.
+4. Build each tab bar entry from `processedTabs`: the label is `tab.name || tab.label`; if `tab.errors` is truthy, wrap the label in a tooltip reading "`{label} has errors`" and append a badge showing the error count; otherwise render the plain label.
+5. Render one tab panel per processed tab (keeping content mounted), showing `tab.content` or a "No content exists" fallback.
+
+> **Key implementation note:** All tab logic (active tab persistence, error counting, tab filtering, PubSub subscriptions) is encapsulated in the composable. It uses `PCore.getNavigationUtils()` for tab persistence, `PCore.getContextTreeManager().onViewMutate()` for field-level error tracking, and `PCore.getMessagingServiceManager()` for case refresh subscriptions.
+
+## Behavioral Contract
+
+### Tab Logic Composable
+
+The extracted tab-logic composable accepts the component's inputs and returns:
+
+- `currentTabId`: currently selected tab index (string, e.g. `'0'`)
+- `handleTabClick`: cached callback for tab selection changes
+- `processedTabs`: array of tab objects augmented with computed `errors` count
+- `instructions`: sanitized HTML string (or empty)
+
+Internally it manages:
+
+- Local state for `currentTabId` and `tabErrors` (record of per-field errors per tab)
+- Instance references for `tabErrors` and `submitAttempted` (to avoid stale closures)
+- Memoized computation for `navigationKey`, `tabItems` (visible tabs), and `processedTabs`
+- Cached callbacks for `handleTabClick`, `updateTabErrorsOnViewMutate`, `navigateToFirstErrorTab`, and `highlightFirstErrorTab`
+
+### Navigation Key Derivation
+
+- `navigationKey` is built from: `{caseInfoId or landingPageViewName}-{metadataName}-HierarchicalForm`
+- `getLandingPageViewName(contextName)`: strips the trailing segment from contextName, then uses `PCore.getContainerUtils().getActiveContainerItemName(target)` and `PCore.getContainerUtils().getContainerItemData(target, activeItemID)` to get `containerItemData.view.config.name`
+- Must be stable across re-renders — derive it once via memoized computation.
+
+### Active Tab Persistence
+
+- On initialization, read persisted tab from `PCore.getNavigationUtils().getComponentState(navigationKey)` — extract `activeTab` from the stored state, or fall back to `getFirstVisibleTabId(deferLoadedTabs)`.
+- On tab change, persist via `PCore.getNavigationUtils().setComponentState(navigationKey, { activeTab: currentTabId })`.
+- Also persist an `ActiveTab` key for the CaseView: `{caseInfoId}-CaseView-ActiveTab` → `{ id: currentTabId }`.
+- On cleanup, if the context is a modal (`getContextName()` includes `/modal`), reset the stored tab to `firstTabId`.
+
+### Deferred Tab Loading
+
+- The first child is a deferred-loaded tabs container. Set the inherited `template` on it via `deferLoadedTabs.getPConnect().setInheritedProp('template', template)`.
+- `tabsFromChildren` is obtained from `deferLoadedTabs.getPConnect().getChildren()`.
+
+### Tab Visibility
+
+- On initialization, iterate the deferred children; for each child whose raw config has a `visibility` property, store `tabsVisibility[index] = rawConfigProps.visibility`.
+- Register additional inputs: `getPConnect().registerAdditionalProps({ tabsVisibility })` and `getPConnect().registerAdditionalProps({ lastUpdateCaseTime: '@P caseInfo.lastUpdateTime' })`.
+- When `tabsVisibility` changes and all values are booleans, serialize them to a string key to trigger tab re-evaluation.
+
+### Case Refresh Subscription
+
+- If `fullCaseId` is available: subscribe to case messages via `PCore.getMessagingServiceManager().getCaseSubscription(fullCaseId).subscribe({ caseId: fullCaseId }, handleCaseRefresh)`.
+- `handleCaseRefresh`: if `message.subtype === 'tab'`, call `refreshTabData()`.
+- On cleanup: unsubscribe from the case subscription.
+
+### Tab Data and Active Tab Sync
+
+- Use a tab-count helper (from the project's SDK utilities) initialized with `(deferLoadedTabs, 'hierarchical', currentTabId, template)` to get `tabData` and `refreshTabData`.
+- Refresh tab data when `lastUpdateCaseTime` changes.
+- When `tabData` changes or tab visibility changes, re-evaluate the active tab via `getActiveTabId(tabData, currentTabId)` and update if changed.
+
+### Error Tracking
+
+- `tabErrors`: a record mapping `tab.id` → `{ fieldName: messages[] }` — tracks per-field validation errors per tab.
+- `updateTabErrorsOnViewMutate(messageObject, tab)`: called by `PCore.getContextTreeManager().onViewMutate()` for each tab's context. If the message type is `MESSAGES_TYPE_ERROR`, adds the field errors; otherwise removes them.
+- Register `onViewMutate` callbacks for each visible tab item, using `tab.getPConnect().getContextName()`, `tab.getPConnect().getPageReference()`, and `tab.getPConnect()._rawConfig.config.name`.
+
+### Error Navigation on Submit
+
+- Subscribe to `PCore.getConstants().PUB_SUB_EVENTS.ERROR_ON_FINISH_ASSIGNMENT`: when triggered, call `highlightFirstErrorTab()` which sets `submitAttempted` to true and navigates to the first tab with errors.
+- Subscribe to `PCore.getConstants().PUB_SUB_EVENTS.CASE_EVENTS.CURRENT_ASSIGNMENT_UPDATED`: when triggered, reset all tab errors and clear `submitAttempted`.
+- When `tabErrors` changes and `submitAttempted` is true, re-navigate to the first error tab (handles late-arriving validation messages).
+
+### Instructions
+
+- Call `getInstructions(getPConnect(), inputs.instructions)` to get sanitized HTML.
+- If non-empty, render as raw HTML content above the tabs.
+
+### Tab Items
+
+- `tabItems`: memoized computation filtering `tabData` to only visible tabs (those where `tab.visibility()` returns true).
+- Each tab has `id`, `name`/`label`, `content`, `errors`, and PConnect methods.
+
+### Error Badge
+
+- `processedTabs`: memoized computation that augments each visible tab with an `errors` count — the total number of error messages across all fields in `tabErrors[tab.id]`.
+- If `errors` is truthy: wrap the tab label with a tooltip reading "`{label} has errors`" and display a badge with the error count.
+- Else: render the label plain.
+
+### Tab Click
+
+- `handleTabClick(event, id)`: cached callback that delegates to `tabClick(id, tabData, currentTabId, setCurrentTabId)` — a shared utility that handles tab selection logic.
+
+### Render
+
+1. Optional instruction block (rendered as raw HTML, above tabs).
+2. Tab context wrapper with value set to `currentTabId`.
+3. Scrollable tab bar containing one tab entry per `processedTabs` item (with error badge label if applicable, text-transform disabled).
+4. Tab panels (kept mounted) per processed tab containing `tab.content` or "No content exists" fallback.
+
+## Visual Specifications
+
+### Tab Bar
+
+| Property    | Value                                                       |
+| ----------- | ----------------------------------------------------------- |
+| Orientation | Horizontal, scrollable                                      |
+| Error badge | Red badge with tooltip showing error count message          |
+| Border      | Bottom border on the tab bar container (1px, divider color) |
+
+**CSS-only implementation notes:**
+
+- Tab bar: `display: flex; border-bottom: 1px solid var(--divider)`.
+- Error badge: red circle badge positioned inline next to the tab label text (not overlaid).
+- Error badge and label wrapped in a flex container with `align-items: center; gap: 0.5rem`.
+- Instruction text: rendered with bottom margin (approximately 0.5rem) above the tab bar.
+- Tab panels: no horizontal padding (panel content fills available width).
+- Tab labels: no text-transform applied (preserve original case).
+
+## Edge Cases & Special Logic
+
+- The tab-count helper tracks validation errors per tab section and must be refreshed on case updates.
+- `getActiveTabId` / `getFirstVisibleTabId` are shared tab utilities — they handle the case where the persisted tab is no longer visible.
+- `navigationKey` must be stable across re-renders — derive it once via memoized computation from the case ID (or landing page view name), metadata name, and the component name.
+- If no visible tabs, render nothing.
+- When the component is in a modal context, reset persisted tab state on cleanup to avoid stale navigation state.
+- The `_rawConfig` property on PConnect is used to access the raw view config name for `onViewMutate` registration.
+- Error navigation on submit attempts only occurs after `ERROR_ON_FINISH_ASSIGNMENT` fires — it does not proactively validate on tab switch.
+- `CURRENT_ASSIGNMENT_UPDATED` clears all error state, preventing stale error badges from persisting across assignment transitions.
+
+## Dependencies
+
+- Tab-logic composable (custom extracted module) — encapsulates all tab state, persistence, and error tracking
+- Tab utility helpers (`getActiveTabId`, `getFirstVisibleTabId`, `tabClick`) — shared tab navigation logic from the project's SubTabs utilities
+- `getInstructions` — shared template utility for sanitizing instruction HTML
+- Tab-count helper from the project's SDK utilities — for computing per-tab validation data
+- `PCore.getNavigationUtils()` — for persisting and retrieving active tab state
+- `PCore.getContextTreeManager().onViewMutate()` — for registering per-field validation error listeners
+- `PCore.getMessagingServiceManager().getCaseSubscription()` — for subscribing to case refresh messages
+- `PCore.getPubSubUtils()` — for subscribing to `ERROR_ON_FINISH_ASSIGNMENT` and `CURRENT_ASSIGNMENT_UPDATED` events
+- `PCore.getContainerUtils()` — for deriving the landing page view name (used in navigation key)
+- `PCore.getConstants()` — for PubSub event keys, message type constants, and case info constants
+
+## Design System Mapping
+
+**UI control type:** Multi-step tabbed form with per-tab error indicators and persistent active tab.
+
+When implementing in a specific design system, map the following:
+
+- **Tab bar container:** Use the design system's horizontal tab strip with scrollable overflow support and a bottom border divider.
+- **Tab entries:** Use the design system's tab trigger component with no text-transform; label text should preserve original case.
+- **Error badge:** Use the design system's inline badge component (red/error color) positioned next to the tab label text within a flex row. Wrap the badge-label group in a tooltip showing "`{label} has errors`".
+- **Tab panels:** Use the design system's tab panel or content container that supports keep-mounted behavior (all panels remain in DOM, only one is visible).
+- **Instruction block:** A block-level element rendering sanitized HTML, positioned above the tab bar with bottom margin spacing.
+- **Layout:** A vertical flex column containing the optional instruction block, the tab bar with bottom border, and the tab panel area.
+
+Implementation constraints regardless of design system:
+
+- Error badge is mandatory — always show error counts when `processedTabs[i].errors > 0`
+- Active tab must be persisted via `PCore.getNavigationUtils()` for correct navigation behavior
+- Instructions HTML renders above the entire tab bar, not per-tab
+- Tab panels must remain mounted (not destroyed on tab switch) to preserve form state
+- On submit error (`ERROR_ON_FINISH_ASSIGNMENT`), automatically navigate to the first tab with errors
+- On assignment update (`CURRENT_ASSIGNMENT_UPDATED`), clear all error badges