@pega/sdk 0.0.5 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/AlertBanner.md

@@ -2,7 +2,7 @@
 
 Alert/notification banner that displays one or more messages with a severity variant and an optional dismiss button.
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
@@ -13,67 +13,61 @@ Renders a visually-styled alert box tied to a Pega `variant` value (urgent, warn
 ## Pega Metadata
 
 - **Pega Name:** `AlertBanner`
-- **Registration key:** `AlertBanner` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives all data as direct props
+- **Registration key:** `AlertBanner` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
 
-## Props
+## Component Inputs
 
-| Prop        | Type                                                        | Required | Description                                                   |
+The component accepts the following inputs. Define the input contract using the project's framework conventions for your target stack.
+
+| Name        | Type                                                        | Required | Description                                                   |
 | ----------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------- |
 | `id`        | `string`                                                    | Yes      | DOM id for the root wrapper element                           |
 | `variant`   | `string`                                                    | Yes      | Alert variant: `'urgent'`, `'warning'`, `'success'`, `'info'` |
 | `messages`  | `Array<string \| { label?: string; description?: string }>` | Yes      | One or more messages (string or structured object)            |
 | `onDismiss` | `function` (optional)                                       | No       | Dismiss/close handler; if provided, show a close button       |
 
-## Component Skeleton
-
-```typescript
-import './AlertBanner.css';
-
-interface AlertBannerProps {
-  id: string;
-  variant: string;
-  messages: Array<string | { label?: string; description?: string }>;
-  onDismiss?: () => void;
-}
-
-const VARIANT_MAP: Record<string, { severity: string; label: string }> = {
-  urgent: { severity: 'error', label: 'Error' },
-  warning: { severity: 'warning', label: 'Warning' },
-  success: { severity: 'success', label: 'Success' },
-  info: { severity: 'info', label: 'Info' },
-};
-
-function renderMessage(message: string | { label?: string; description?: string }) {
-  if (typeof message === 'object' && message !== null) {
-    const { label = '', description = '' } = message;
-    return label ? <><strong>{label}</strong> {description}</> : <>{description}</>;
-  }
-  const colonIndex = message.indexOf(':');
-  if (colonIndex === -1) return message;
-  return <><strong>{message.slice(0, colonIndex + 1)}</strong>{message.slice(colonIndex + 1)}</>;
-}
-
-export default function AlertBanner({ id, variant, messages, onDismiss }: AlertBannerProps) {
-  const { severity, label } = VARIANT_MAP[variant] ?? VARIANT_MAP.info;
-  const isMultiple = messages.length > 1;
-
-  return (
-    <div id={id}>
-      <AlertWidget variant="outlined" severity={severity} onClose={onDismiss}>
-        {isMultiple && (
-          <AlertTitle>
-            {label} <CountBadge variant={variant}>{messages.length}</CountBadge>
-          </AlertTitle>
-        )}
-        {isMultiple
-          ? <ul className="alert-banner-list">{messages.map((m, i) => <li key={i}>{renderMessage(m)}</li>)}</ul>
-          : renderMessage(messages[0])}
-      </AlertWidget>
-    </div>
-  );
-}
-```
+## Implementation Structure
+
+### Module Setup
+
+The component requires companion styles (for badge and list styling) that should be co-located with the component following the project's styling convention. It does NOT import any Pega SDK modules — all data arrives via direct inputs.
+
+The component is named `AlertBanner` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Variant Map (module-level constant)
+
+Define a module-level lookup object that maps Pega variant strings to a UI severity value and a human-readable display label:
+
+| Pega Variant | Severity Value | Display Label |
+| ------------ | -------------- | ------------- |
+| `urgent`     | `error`        | `Error`       |
+| `warning`    | `warning`      | `Warning`     |
+| `success`    | `success`      | `Success`     |
+| `info`       | `info`         | `Info`        |
+
+The map is typed as `Record<string, { severity: string; label: string }>`.
+
+### Helper: `renderMessage`
+
+Define a private helper function `renderMessage` that accepts a single message (either a string or an object with optional `label` and `description` fields) and returns formatted markup. The function follows this decision tree:
+
+1. **Object with truthy `label`** — render the label in a bold/strong element followed by a space and the `description` text.
+2. **Object without `label`** (label is falsy/empty) — render only the `description` text.
+3. **String containing a colon (`:`)** — find the index of the **first** colon only. Render everything from the start up to and including the colon in a bold/strong element, then render the remainder as plain text.
+4. **String with no colon** — render the entire string as plain text with no formatting.
+
+### Component Logic
+
+The component receives `id`, `variant`, `messages`, and `onDismiss` as inputs, then:
+
+1. **Resolve variant** — look up `variant` in the variant map. If the variant is not found (unknown/missing), fall back to the `info` entry.
+2. **Determine plurality** — check whether `messages.length > 1` to decide between single-message and multi-message rendering.
+3. **Render tree:**
+   - Outer wrapper: a plain `<div>` with the `id` input as its DOM id.
+   - Inside the wrapper: a design-system alert component displayed in **outlined** style, with the resolved `severity` passed as the severity/type attribute. If `onDismiss` is provided, wire it as the alert's close handler; otherwise omit the close button entirely.
+   - **Multiple messages path:** display an alert title row containing the display label text and a circular count badge (showing `messages.length`). Below the title, display messages as an unordered list (`<ul>` with class `alert-banner-list`), with each message processed via `renderMessage` inside a `<li>`.
+   - **Single message path:** display `renderMessage(messages[0])` directly as the alert's content (no title, no list).
 
 ## Behavioral Contract
 
@@ -97,7 +91,7 @@ export default function AlertBanner({ id, variant, messages, onDismiss }: AlertB
 
 ## Visual Specifications
 
-Derived from `AlertBanner.css` and MUI Alert usage:
+Derived from the component's companion styles and the reference implementation's alert usage:
 
 ### Alert Container
 
@@ -166,22 +160,14 @@ Derived from `AlertBanner.css` and MUI Alert usage:
 
 **UI control type:** Alert / Notification banner with severity levels.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                                   |
-| ------------------ | --------------------------------------------------------------------------------------- |
-| Default (CSS only) | `<div role="alert">` with severity border + inline close button                         |
-| MUI                | `<Alert variant='outlined' severity={severity} onClose={onDismiss}><AlertTitle>`        |
-| Ant Design         | `<Alert type={type} message={title} description={…} closable banner />`                 |
-| Chakra UI          | `<Alert status={status}><AlertIcon /><AlertTitle /><AlertDescription /><CloseButton />` |
-| Shadcn/ui          | Custom `<Alert>` with `variant` prop                                                    |
-
-When implementing in a specific design system, map the following:
-
-- `variant='urgent'` → `severity/type/status='error'` or `'danger'`
-- `variant='warning'` → `severity/type/status='warning'`
-- `variant='success'` → `severity/type/status='success'`
-- `variant='info'` → `severity/type/status='info'`
-- `onDismiss` → `onClose` / `closable` / close button prop
-- Multiple messages → render as a list inside the alert description area
-- Badge count → render as a tag/badge chip next to the title
+When implementing in a specific design system, use the DS's alert/notification component and map the following:
+
+- `variant='urgent'` → the DS's error/danger severity level
+- `variant='warning'` → the DS's warning severity level
+- `variant='success'` → the DS's success severity level
+- `variant='info'` → the DS's info/informational severity level
+- `onDismiss` → the DS alert's close/dismiss handler (e.g., `onClose`, `closable`, or a close button slot)
+- The alert should render in an **outlined** style (visible border, no filled background) if the DS supports that variant; otherwise use the closest equivalent that shows a colored border indicating severity
+- Multiple messages → render as a list inside the alert's description/content area
+- Badge count → render as a small circular tag/badge element next to the title text
+- If the DS has no built-in alert component, use a `<div role="alert">` with a severity-colored left border or outline, and render a custom close button if `onDismiss` is provided

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/Banner.md

@@ -2,7 +2,7 @@
 
 Promotional/informational banner with a full-width background image hero section and a two-column content layout below it.
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
@@ -11,72 +11,61 @@ Promotional/informational banner with a full-width background image hero section
 Renders a visually rich banner composed of two parts:
 
 1. **Hero section:** Full-width area with a background image, centered title and message text overlaid.
-2. **Content columns:** Two adjustable-width columns below the hero, rendered from the `a` and `b` slot props. Column widths are controlled by the `variant` prop.
+2. **Content columns:** Two adjustable-width columns below the hero, rendered from the `a` and `b` slot inputs. Column widths are controlled by the `variant` input.
 
 ## Pega Metadata
 
 - **Pega Name:** `Banner`
-- **Registration key:** `Banner` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives all data as direct props
-
-## Props
-
-| Prop                     | Type        | Required | Description                                                        |
-| ------------------------ | ----------- | -------- | ------------------------------------------------------------------ |
-| `a`                      | `ReactNode` | Yes      | Content for the first (left/narrower) column                       |
-| `b`                      | `ReactNode` | Yes      | Content for the second (right/wider) column                        |
-| `banner`                 | `object`    | Yes      | Banner metadata (see sub-props below)                              |
-| `banner.title`           | `string`    | Yes      | Title text displayed in the hero section                           |
-| `banner.message`         | `string`    | Yes      | Descriptive message text in the hero section                       |
-| `banner.backgroundImage` | `string`    | Yes      | URL of the background image for the hero section                   |
-| `banner.variant`         | `any`       | No       | Unused internally (layout variant comes from top-level `variant`)  |
-| `banner.backgroundColor` | `any`       | No       | Unused internally                                                  |
-| `banner.tintImage`       | `any`       | No       | Unused internally                                                  |
-| `variant`                | `string`    | Yes      | Column layout: `'two-column'`, `'narrow-wide'`, or `'wide-narrow'` |
-
-## Component Skeleton
-
-```typescript
-import './Banner.css';
-
-interface BannerProps {
-  a: any; b: any;
-  banner?: { title?: string; message?: string; backgroundImage?: string; variant?: any; backgroundColor?: any; tintImage?: any };
-  variant: string;
-}
-
-export default function Banner(props: BannerProps) {
-  const { a, b, banner = {}, variant } = props;
-  const { title, message, backgroundImage } = banner;
-  const variantMap = {
-    'two-column': [6, 6],
-    'narrow-wide': [4, 8],
-    'wide-narrow': [8, 4],
-  };
-
-  return (
-    <div style={{ marginBottom: '2rem' }}>
-      {/* Hero section */}
-      <div className="background-image-style" style={{ backgroundImage: `url(${backgroundImage})` }}>
-        <div className="background-style content">
-          <h1 className="title">{title}</h1>
-          <p className="message">{message}</p>
-        </div>
-      </div>
-      {/* Content columns */}
-      <GridContainer spacing={1}>
-        <GridItem xs={variantMap[variant][0]}
-          style={{ padding: '1rem', backgroundColor: 'var(--app-form-bg-color)', borderRadius: '16px', height: 'fit-content' }}>
-          {a}
-        </GridItem>
-        <GridItem xs={variantMap[variant][1]} style={{ padding: '0 1rem' }}>
-          {b}
-        </GridItem>
-      </GridContainer>
-    </div>
-  );
-}
-```
+- **Registration key:** `Banner` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
+
+## Component Inputs
+
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name                     | Type               | Required | Description                                                        |
+| ------------------------ | ------------------ | -------- | ------------------------------------------------------------------ |
+| `a`                      | renderable content | Yes      | Content for the first (left/narrower) column                       |
+| `b`                      | renderable content | Yes      | Content for the second (right/wider) column                        |
+| `banner`                 | `object`           | Yes      | Banner metadata (see sub-fields below)                             |
+| `banner.title`           | `string`           | Yes      | Title text displayed in the hero section                           |
+| `banner.message`         | `string`           | Yes      | Descriptive message text in the hero section                       |
+| `banner.backgroundImage` | `string`           | Yes      | URL of the background image for the hero section                   |
+| `banner.variant`         | `any`              | No       | Unused internally (layout variant comes from top-level `variant`)  |
+| `banner.backgroundColor` | `any`              | No       | Unused internally                                                  |
+| `banner.tintImage`       | `any`              | No       | Unused internally                                                  |
+| `variant`                | `string`           | Yes      | Column layout: `'two-column'`, `'narrow-wide'`, or `'wide-narrow'` |
+
+## Implementation Structure
+
+### Module Setup
+
+The component requires companion styles (for hero section and layout styling) that should be co-located with the component following the project's styling convention. It does NOT import any Pega SDK modules — all data arrives via direct inputs.
+
+The component is named `Banner` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Variant Map (module-level or function-level constant)
+
+Define a lookup object that maps the `variant` string to a pair of column width values (out of 12):
+
+| Variant       | Column A (first) | Column B (second) |
+| ------------- | ---------------- | ----------------- |
+| `two-column`  | 6                | 6                 |
+| `narrow-wide` | 4                | 8                 |
+| `wide-narrow` | 8                | 4                 |
+
+### Component Logic
+
+The component receives `a`, `b`, `banner` (defaults to `{}`), and `variant` as inputs. From `banner`, extract `title`, `message`, and `backgroundImage`. The render tree is:
+
+1. **Outer wrapper** — a `<div>` with `marginBottom: 2rem`.
+2. **Hero section:**
+   - A `<div>` with class `background-image-style` and inline style `backgroundImage: url({backgroundImage})`.
+   - Inside: an overlay `<div>` with classes `background-style content`.
+   - Inside the overlay: `<h1>` with class `title` containing the title text, and `<p>` with class `message` containing the message text.
+3. **Content columns** — below the hero, a 12-column grid container with `spacing={1}` containing two grid items:
+   - **Column A** (first child slot): grid item sized to the first value from the variant map. Styled with `padding: 1rem; background-color: var(--app-form-bg-color); border-radius: 16px; height: fit-content`. Renders `{a}`.
+   - **Column B** (second child slot): grid item sized to the second value from the variant map. Styled with `padding: 0 1rem` (no background). Renders `{b}`.
 
 ## Behavioral Contract
 
@@ -96,15 +85,15 @@ export default function Banner(props: BannerProps) {
 
 ## Layout Variants
 
-```
-two-column:   [A 50%]  [B 50%]
-narrow-wide:  [A 33%]  [B 67%]
-wide-narrow:  [A 67%]  [B 33%]
-```
+| Variant       | Column A | Column B |
+| ------------- | -------- | -------- |
+| `two-column`  | 50% (6)  | 50% (6)  |
+| `narrow-wide` | 33% (4)  | 67% (8)  |
+| `wide-narrow` | 67% (8)  | 33% (4)  |
 
 ## Visual Specifications
 
-Derived from `Banner.css`:
+Derived from the component's companion styles:
 
 ### Hero Section
 
@@ -167,7 +156,7 @@ Derived from `Banner.css`:
 
 - If `backgroundImage` is an empty string or undefined, the hero section renders without a background image (transparent/color background).
 - If `variant` is not one of the three known values, implement a safe default (e.g., `'two-column'`).
-- The `banner.backgroundColor`, `banner.variant`, and `banner.tintImage` props are received but not rendered in the reference implementation.
+- The `banner.backgroundColor`, `banner.variant`, and `banner.tintImage` inputs are received but not rendered in the reference implementation.
 
 ## Dependencies
 
@@ -178,19 +167,10 @@ Derived from `Banner.css`:
 
 **UI control type:** Full-width banner hero with responsive two-column content area.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                     |
-| ------------------ | ------------------------------------------------------------------------- |
-| Default (CSS only) | CSS Grid for columns, CSS background for hero                             |
-| MUI                | `<Grid container size={12}>` with `<Grid size={{ xs: ... }}>` for columns |
-| Ant Design         | `<Row gutter={8}>` with `<Col span={...}>` for columns                    |
-| Chakra UI          | `<SimpleGrid columns={2}>` or `<Grid templateColumns='...'>`              |
-| Shadcn/ui          | CSS Grid with Tailwind column utilities                                   |
-
 When implementing in a specific design system, map the following:
 
-- `variant` column widths → grid column span values
-- Background image hero → `backgroundImage` inline style with `background-size: cover`
-- Column A (card-like) → design system's Card or `bg` prop with border-radius
-- Column B (plain) → plain container with horizontal padding only
+- **Column layout** → use the DS's grid/column system to create two responsive columns. Map the variant column ratios (6/6, 4/8, 8/4 out of 12) to the DS's grid column sizing convention (span values, fractional units, or percentage widths).
+- **Background image hero** → use inline `backgroundImage` style with `background-size: cover; background-position: center`. No DS component is needed for this — it's always a styled `<div>`.
+- **Column A (card-like)** → use the DS's card component or a container with background color and border-radius (if available). Otherwise use a plain `<div>` with the specified styles.
+- **Column B (plain)** → a plain container with horizontal padding only (no background).
+- **Responsive** → on small viewports (mobile), collapse the two columns to a single stacked column.