@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.claude/skills/template-skills/SingleReferenceReadOnly.md

@@ -1,108 +0,0 @@
-# Skill: SingleReferenceReadOnly
-
-Single reference read-only template. Renders a read-only reference field as a semantic link for editable field types, or as a plain label otherwise.
-
-> **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 single data reference field in read-only mode. For fields that were displayed as editable selection controls (autocomplete, table select, dropdown), renders a `SemanticLink` component so the reference value is clickable/navigable. For other display types, renders a plain read-only label.
-
-## Pega Metadata
-
-- **Registration key:** `SingleReferenceReadOnly` (in `component-map.ts`)
-- **Category:** Display template — read-only reference
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop              | Type       | Required | Description                                               |
-| ----------------- | ---------- | -------- | --------------------------------------------------------- |
-| `label`           | `string`   | Yes      | Field label                                               |
-| `displayAs`       | `string`   | Yes      | The edit-mode display type this field was configured with |
-| `value`           | `string`   | No       | Current field value (display text)                        |
-| `caseClass`       | `string`   | No       | Class identifier for the referenced case                  |
-| `text`            | `string`   | No       | Display text for the semantic link                        |
-| `caseID`          | `string`   | No       | Case ID for the semantic link                             |
-| `contextPage`     | `string`   | No       | Context page identifier                                   |
-| `resourceParams`  | `object`   | No       | Parameters for the referenced resource                    |
-| `resourcePayload` | `object`   | No       | Payload for resource navigation                           |
-| `getPConnect`     | `function` | Yes      | PConnect getter                                           |
-
-## Behavioral Contract
-
-### Editable Component Check
-
-```
-editableComponents = ['AutoComplete', 'SimpleTableSelect', 'Dropdown']
-```
-
-If `displayAs` is in `editableComponents`:
-
-1. Build config with: `caseClass`, `text`, `caseID`, `contextPage`, `resourceParams`, `resourcePayload`.
-2. Create: `createComponent({ type: 'SemanticLink', config: { ...builtConfig } })`.
-3. Render the created `SemanticLink` component.
-
-Else:
-
-- Render a plain read-only display using `<FormControl variant='standard'>` + `<FormLabel>` + value text.
-
-### Layout
-
-For both variants, wrap with:
-
-```tsx
-<FormControl variant="standard" sx={{ flexDirection: 'row' }}>
-  <FormLabel sx={{ marginRight: '2rem' }}>{label}</FormLabel>
-  {semanLinkOrValue}
-</FormControl>
-```
-
-## Visual Specifications
-
-| Variant         | Layout                                |
-| --------------- | ------------------------------------- |
-| SemanticLink    | Label (left) + clickable link (right) |
-| Plain read-only | Label (left) + plain text (right)     |
-
-**CSS-only implementation notes:**
-
-- Wrapper: `display: flex; flex-direction: row; align-items: baseline; gap: 1rem`.
-- Label: `font-size: 0.875rem; color: var(--secondary-text-color); min-width: 120px`.
-- Semantic link: `color: var(--link-color); text-decoration: underline; cursor: pointer`.
-- Plain value: `font-size: 0.875rem; color: var(--primary-text-color)`.
-
-## Edge Cases & Special Logic
-
-- `displayAs` check is case-sensitive — values are `'AutoComplete'`, `'SimpleTableSelect'`, `'Dropdown'` (exact match).
-- `createComponent` returns a PConnect config — render via `createElement(PConnectComponent, { ...createdConfig })`.
-- If `text` is empty/undefined, the semantic link shows the `caseID` as fallback text.
-- `SemanticLink` navigation requires `caseClass` and `caseID` — if either is missing, fall back to plain read-only display.
-
-## Dependencies
-
-- `PConnectComponent` from `@pega/sdk-react` — for rendering the `SemanticLink`
-- `getPConnect().createComponent()` — creates the SemanticLink component config
-- MUI: `<FormControl>`, `<FormLabel>`
-
-## Design System Mapping
-
-**UI control type:** Read-only reference field — semantic link for navigable references, plain label otherwise.
-
-Listed design systems are examples only.
-
-| Design System      | Semantic Link                                 | Plain Read-Only     |
-| ------------------ | --------------------------------------------- | ------------------- |
-| Default (CSS only) | `<a>` with case navigation                    | `<span>`            |
-| MUI                | `SemanticLink` rendered via `createComponent` | `<Typography>`      |
-| Ant Design         | `<Typography.Link>`                           | `<Typography.Text>` |
-| Chakra UI          | `<Link>`                                      | `<Text>`            |
-| Shadcn/ui          | Custom link                                   | `<span>`            |
-
-When implementing in a specific design system:
-
-- The `editableComponents` list (`'AutoComplete'`, `'SimpleTableSelect'`, `'Dropdown'`) controls semantic link vs plain display
-- `SemanticLink` must be rendered via `createComponent` — do not implement the link logic directly in this component
-- Horizontal label + value layout (row direction) is required

package/templates/react-sdk-reference/.claude/skills/template-skills/SubTabs.md

@@ -1,82 +0,0 @@
-# Skill: SubTabs
-
-Sub-tabs navigation template. Renders a tab container for case view sections using shared tab utilities with deferred content loading.
-
-> **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 horizontal tab bar for navigating between case view sections. Uses shared `tabUtils` for tab state management (visible tabs, transient tabs, tab click). Tab content is deferred — only the active tab loads content. No section heading.
-
-## Pega Metadata
-
-- **Registration key:** `SubTabs` (in `component-map.ts`)
-- **Category:** Navigation template
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop          | Type          | Required | Description                                         |
-| ------------- | ------------- | -------- | --------------------------------------------------- |
-| `children`    | `ReactNode[]` | Yes      | `children[0]` is the deferred-loaded tabs container |
-| `getPConnect` | `function`    | Yes      | PConnect getter                                     |
-
-## Behavioral Contract
-
-1. **Extract deferred tabs:** `deferLoadedTabs = Children.toArray(children)[0]`.
-2. **State:** `currentTabId` (string, default `'0'`), `tabItems` (array).
-3. **Compute visible tabs:** `getVisibleTabs(deferLoadedTabs, 'tabsSubs')` in `useEffect([deferLoadedTabs])` → `availableTabs`.
-4. **Transient tabs:** `useEffect([currentTabId])` → `setTabItems(getTransientTabs(availableTabs, currentTabId, tabItems))`.
-5. **Tab click:** `tabClick(index, availableTabs, currentTabId, setCurrentTabId, tabItems)` from `tabUtils`.
-6. **Render:**
-   - `<TabContext value={currentTabId}>`
-   - `<Tabs onChange={handleTabClick} value={currentTabId}>` — one `<Tab>` per `tabItems`
-   - One `<TabPanel>` per `tabItems` with `tab.content || ''`
-7. No section heading (unlike `DetailsSubTabs`).
-
-> **Difference from `DetailsSubTabs`:** SubTabs has no `label`/`showLabel` props and no `<h3>` heading. Uses `'tabsSubs'` identifier for `getVisibleTabs` (vs `'detailsSubTabs'`).
-
-## Visual Specifications
-
-Identical to `DetailsSubTabs` except no heading above the tab bar.
-
-**CSS-only implementation notes:**
-
-- Tab bar: `display: flex; border-bottom: 2px solid var(--divider)`.
-- Each tab: `padding: 8px 16px; cursor: pointer; border-bottom: 2px solid transparent`.
-- Active tab: `border-bottom-color: var(--app-primary-color); font-weight: 600`.
-- Tab panel: `padding: 16px 0`.
-
-## Edge Cases & Special Logic
-
-See `DetailsSubTabs.md` for shared edge cases. Additional:
-
-- `tabUtils` identifier string `'tabsSubs'` must match exactly — it is used internally by `getVisibleTabs` for scoping.
-
-## Dependencies
-
-- `getTransientTabs`, `getVisibleTabs`, `tabClick` from `./tabUtils`
-- `TabContext`, `TabPanel` from `@mui/lab`
-- `Tab`, `Tabs` from `@mui/material`
-
-## Design System Mapping
-
-**UI control type:** Tab navigation container — no heading, deferred content loading.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                    |
-| ------------------ | -------------------------------------------------------- |
-| Default (CSS only) | Custom tab bar with CSS underline indicator              |
-| MUI                | `<TabContext>` + `<Tabs>` + `<TabPanel>` from `@mui/lab` |
-| Ant Design         | `<Tabs>` with `items` array                              |
-| Chakra UI          | `<Tabs>` + `<TabList>` + `<TabPanels>`                   |
-| Shadcn/ui          | `<Tabs>` + `<TabsList>` + `<TabsContent>`                |
-
-When implementing in a specific design system:
-
-- Use `getVisibleTabs(tabs, 'tabsSubs')` — the identifier string must be `'tabsSubs'`
-- No heading above the tab bar (unlike `DetailsSubTabs`)
-- Deferred loading: content populates lazily via `getTransientTabs`

package/templates/react-sdk-reference/.claude/skills/template-skills/TwoColumn.md

@@ -1,133 +0,0 @@
-# Skill: TwoColumn
-
-Two-column layout template that splits children into two responsive grid columns with configurable width ratios.
-
-> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
-
----
-
-## Component Purpose
-
-Renders two child components side by side in a responsive grid. Column widths are driven by the `templateCol` prop (e.g., `'1fr 1fr'`, `'2fr 1fr'`). On mobile (`xs`), both columns collapse to full width. Three closely related sub-variants share this same layout logic:
-
-- **`TwoColumn`** — core layout, used inside forms and views
-- **`TwoColumnPage`** — thin wrapper that delegates to `TwoColumn` via the component registry
-- **`TwoColumnTab`** — identical layout implementation used inside tab contexts
-
-## Pega Metadata
-
-| Variant       | Registration Key |
-| ------------- | ---------------- |
-| TwoColumn     | `TwoColumn`      |
-| TwoColumnPage | `TwoColumnPage`  |
-| TwoColumnTab  | `TwoColumnTab`   |
-
-All three extend `PConnProps`. Children are received as React `children` (not via `getPConnect().getChildren()`).
-
-## Props
-
-| Prop          | Type          | Required | Description                                                                    |
-| ------------- | ------------- | -------- | ------------------------------------------------------------------------------ |
-| `children`    | `ReactNode[]` | Yes      | Exactly 2 children (left column, right column)                                 |
-| `templateCol` | `string`      | No       | Column width ratio string, e.g., `'1fr 1fr'`, `'2fr 1fr'`. Default `'1fr 1fr'` |
-
-## Sub-Variants
-
-### TwoColumnPage
-
-Thin pass-through wrapper. Retrieves `TwoColumn` from the component registry and renders it with all props forwarded:
-
-```typescript
-const TwoColumn = getComponentFromRegistry('TwoColumn');
-return <TwoColumn {...props} />;
-```
-
-### TwoColumnTab
-
-Identical implementation to `TwoColumn` — same grid layout, same `templateCol` parsing, same column styles. Registered separately under `TwoColumnTab` key to support tab context rendering.
-
-## Behavioral Contract
-
-1. Accept exactly 2 children. If a different count is received, log an error (console only — still render).
-2. Parse `templateCol` to compute MUI Grid column sizes:
-   - Strip unit suffixes (e.g., `'fr'`) from each token using regex: `.replaceAll(/[a-z]+/g, '')`.
-   - Split on whitespace and convert to numbers.
-   - Compute `totalCols = sum(colArray)`.
-   - Compute `ratio = 12 / totalCols`.
-   - `aSize = ratio * colArray[0]`, `bSize = ratio * colArray[1]` (both clamped to MUI's 1–12 GridSize range).
-3. Render a Grid container with `spacing={1}`.
-4. Render `children[0]` in the left column at `size={{ xs: 12, md: aSize }}`.
-5. Render `children[1]` in the right column at `size={{ xs: 12, md: bSize }}`.
-6. Apply `colStyles` class to each column: `display: grid; gap: 1rem; alignContent: baseline`.
-
-## Visual Specifications
-
-Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
-
-### Column Style
-
-| Property      | Value                                 |
-| ------------- | ------------------------------------- |
-| Display       | grid                                  |
-| Gap           | 1rem                                  |
-| Align content | baseline (children stack top-aligned) |
-
-### Grid Spacing
-
-| Property          | Value                     |
-| ----------------- | ------------------------- |
-| Container spacing | 1 (≈ 8px between columns) |
-
-### Responsive Behavior
-
-| Breakpoint    | Column A           | Column B                         |
-| ------------- | ------------------ | -------------------------------- |
-| xs (mobile)   | 12/12 (full width) | 12/12 (full width, stacks below) |
-| md+ (desktop) | `aSize`/12         | `bSize`/12                       |
-
-**Column ratio examples:**
-
-| `templateCol` | Column A   | Column B   |
-| ------------- | ---------- | ---------- |
-| `'1fr 1fr'`   | 6/12 (50%) | 6/12 (50%) |
-| `'2fr 1fr'`   | 8/12 (67%) | 4/12 (33%) |
-| `'1fr 2fr'`   | 4/12 (33%) | 8/12 (67%) |
-| `'3fr 1fr'`   | 9/12 (75%) | 3/12 (25%) |
-
-**CSS-only implementation notes:**
-
-- Column container: `display: grid; gap: 1rem; align-content: start`.
-- Outer grid: `display: grid; grid-template-columns: <aFraction>fr <bFraction>fr; gap: 8px`.
-- Mobile: `grid-template-columns: 1fr` (single column stack).
-- Each column has `display: grid; gap: 1rem; align-content: baseline` for internal stacking.
-
-## Edge Cases & Special Logic
-
-- Default `templateCol` is `'1fr 1fr'` (equal split) when not provided.
-- The `templateCol` parsing is regex-based — any non-numeric suffix is stripped. If only numbers are provided (e.g., `'6 6'`), it still works.
-- `TwoColumnPage` uses `getComponentFromRegistry('TwoColumn')` — if the registry returns an override, that override is used instead of the default `TwoColumn` implementation.
-
-## Dependencies
-
-- `TwoColumnPage`: `getComponentFromRegistry` from `@pega/sdk-react` — to resolve the `TwoColumn` component at runtime
-- `TwoColumn` / `TwoColumnTab`: no special dependencies beyond layout
-
-## Design System Mapping
-
-**UI control type:** Responsive two-column grid layout.
-
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                |
-| ------------------ | -------------------------------------------------------------------- |
-| Default (CSS only) | CSS Grid with `grid-template-columns: <a>fr <b>fr; gap: 8px`         |
-| MUI                | `<Grid container spacing={1}><Grid size={{ xs: 12, md: N }}>`        |
-| Ant Design         | `<Row gutter={8}><Col xs={24} md={N * 2}>` (Ant uses 24-column grid) |
-| Chakra UI          | `<SimpleGrid columns={{ base: 1, md: 2 }} spacing={2}>`              |
-| Shadcn/ui          | Tailwind `grid grid-cols-1 md:grid-cols-[<a>fr_<b>fr] gap-2`         |
-
-When implementing in a specific design system:
-
-- Parse `templateCol` using the same ratio algorithm (strip units, divide 12 by total)
-- Apply `align-content: baseline` so children within each column stack top-aligned
-- Collapse to single column on mobile breakpoint

package/templates/react-sdk-reference/.claude/skills/template-skills/WssNavBar.md

@@ -1,139 +0,0 @@
-# Skill: WssNavBar
-
-WSS (Web Self-Service) navigation bar template. Renders the app bar for WSS portal with responsive hamburger menu, navigation links, operator avatar, and logout.
-
-> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
-
----
-
-## Component Purpose
-
-Provides the top navigation bar for WSS (Web Self-Service) portals. Responsive: shows a hamburger menu on mobile, full nav links on desktop. Navigation position and alignment are configurable. Includes operator avatar with initials and a logout action.
-
-## Pega Metadata
-
-- **Registration key:** `WssNavBar` (in `component-map.ts`)
-- **Category:** Navigation template — WSS portal
-- **Extends:** `PConnProps`
-
-## Props
-
-| Prop                | Type       | Required | Description                                           |
-| ------------------- | ---------- | -------- | ----------------------------------------------------- |
-| `links`             | `array`    | Yes      | Array of `{ label, url, id }` navigation link objects |
-| `navDisplayOptions` | `object`   | No       | `{ alignment: 'left'                                  | 'right' | 'center', position: 'inline' | 'below' }` |
-| `portalLogoUrl`     | `string`   | No       | URL for the portal logo image                         |
-| `operatorInfo`      | `object`   | No       | `{ displayName: string }` — for avatar initials       |
-| `getPConnect`       | `function` | Yes      | PConnect getter                                       |
-
-## Behavioral Contract
-
-### Responsive Layout
-
-- **Mobile (xs breakpoint):** Hamburger menu button (`<MenuIcon>`) shown; nav links hidden.
-  - On click: opens a `<Drawer>` or dropdown menu with nav links.
-  - CSS: `display: { xs: 'flex', md: 'none' }` on hamburger; `display: { xs: 'none', md: 'flex' }` on nav links.
-- **Desktop (md+ breakpoint):** Nav links shown inline; hamburger hidden.
-
-### Navigation Position
-
-From `navDisplayOptions.position`:
-
-- `'inline'` — nav links appear in the same row as the logo.
-- `'below'` — nav links appear in a second row below the logo/title row.
-
-### Navigation Alignment
-
-From `navDisplayOptions.alignment`:
-
-- `'left'` — links flush left.
-- `'right'` — links pushed to the right (flex with `ml: 'auto'`).
-- `'center'` — links centered.
-
-### Operator Avatar
-
-- Extract initials from `operatorInfo.displayName`:
-  - Split by space, take first letter of first and last word.
-  - E.g. `"John Smith"` → `"JS"`.
-- Render as `<Avatar>{initials}</Avatar>`.
-- Clicking avatar opens a menu with a Logout option.
-
-### Logout
-
-- Import `logout` from `@pega/auth/lib/sdk-auth-manager`.
-- Call `logout()` when the Logout menu item is clicked.
-
-### Render Structure
-
-```
-<AppBar position='static'>
-  <Toolbar>
-    {/* Logo */}
-    {portalLogoUrl && <img src={portalLogoUrl} alt='logo' />}
-
-    {/* Hamburger (mobile) */}
-    <IconButton sx={{ display: { xs: 'flex', md: 'none' } }} onClick={openMobileMenu}>
-      <MenuIcon />
-    </IconButton>
-
-    {/* Nav links (desktop) */}
-    <Box sx={{ display: { xs: 'none', md: 'flex' }, ...alignmentStyles }}>
-      {links.map(link => <Button key={link.id} href={link.url}>{link.label}</Button>)}
-    </Box>
-
-    {/* Operator avatar */}
-    <Avatar onClick={openUserMenu}>{initials}</Avatar>
-  </Toolbar>
-</AppBar>
-```
-
-## Visual Specifications
-
-| Element   | Mobile                  | Desktop               |
-| --------- | ----------------------- | --------------------- |
-| Logo      | Shown                   | Shown                 |
-| Nav links | Hidden (hamburger menu) | Shown inline or below |
-| Avatar    | Shown                   | Shown                 |
-| Hamburger | Shown                   | Hidden                |
-
-**CSS-only implementation notes:**
-
-- App bar: `background: var(--app-primary-color); color: white`.
-- Toolbar: `display: flex; align-items: center; gap: 1rem; padding: 0 1rem`.
-- Hamburger: `display: none`. At mobile breakpoint: `display: flex`.
-- Nav links: `display: flex; gap: 0.5rem`. At mobile breakpoint: `display: none`.
-- Avatar: `width: 36px; height: 36px; border-radius: 50%; background: var(--avatar-bg); cursor: pointer`.
-- Logout menu: `position: absolute; top: 100%; right: 0; background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.2)`.
-
-## Edge Cases & Special Logic
-
-- `portalLogoUrl` is async — show fallback text until resolved.
-- `operatorInfo.displayName` may be undefined — guard and show a default avatar (single letter or icon).
-- `navDisplayOptions` may be absent — default to `{ alignment: 'left', position: 'inline' }`.
-- Mobile drawer state must be managed separately from the user menu state.
-
-## Dependencies
-
-- `logout` from `@pega/auth/lib/sdk-auth-manager` — logout handler
-- MUI: `<AppBar>`, `<Toolbar>`, `<IconButton>`, `<Avatar>`, `<Menu>`, `<MenuItem>`, `<Button>`, `<Box>`
-- MUI Icons: `<MenuIcon>`
-
-## Design System Mapping
-
-**UI control type:** Responsive application navigation bar with avatar and logout.
-
-Listed design systems are examples only.
-
-| Design System      | App Bar                  | Avatar                 | Mobile Menu              |
-| ------------------ | ------------------------ | ---------------------- | ------------------------ |
-| Default (CSS only) | `<header>` + CSS         | `<div class='avatar'>` | CSS hamburger + dropdown |
-| MUI                | `<AppBar>` + `<Toolbar>` | `<Avatar>`             | `<Drawer>` or `<Menu>`   |
-| Ant Design         | `<Layout.Header>`        | `<Avatar>`             | `<Drawer>`               |
-| Chakra UI          | `<Box as='header'>`      | `<Avatar>`             | `<Drawer>`               |
-| Shadcn/ui          | Custom `<header>`        | Custom initials avatar | `<Sheet>` (drawer)       |
-
-When implementing in a specific design system:
-
-- `logout` from `@pega/auth/lib/sdk-auth-manager` is mandatory — always call the SDK logout, not a custom one
-- Responsive breakpoints for hamburger/nav visibility must be implemented
-- `navDisplayOptions.alignment` and `.position` must be respected