Skip to content

Component_Build_Guide.md

Latest commit

 

History

History
286 lines (223 loc) · 19.9 KB

Component_Build_Guide.md

File metadata and controls

286 lines (223 loc) · 19.9 KB

Component Build & Documentation Guide

Welcome to the Confluence of the Constellation UI Gallery – this file is the one‑stop reference for anyone who wants to add a new Pega extension component to the gallery or understand the structure of an existing one.

1️⃣ Quick Overview – List of Existing Components

Component Short Description Docs
Pega_Extensions_ActionableButton A button that can trigger Pega actions or workflows. Docs
Pega_Extensions_AutoSave Automatically saves form data as the user types or changes fields. Docs
Pega_Extensions_Banner Displays a banner message, typically for notifications or alerts. Docs
Pega_Extensions_BannerInput Combines a banner with an input field for quick data entry. Docs
Pega_Extensions_BarCode Generates and scans barcodes. Docs
Pega_Extensions_Calendar Calendar view for selecting dates, with support for events. Docs
Pega_Extensions_CameraCapture Lets users take photos using their device camera and save them directly as case attachments. Docs
Pega_Extensions_CardGallery Displays items in a card‑style gallery layout. Docs
Pega_Extensions_CaseLauncher Launches Pega cases or tasks from the UI. Docs
Pega_Extensions_CaseReference References a Pega case, showing key details. Docs
Pega_Extensions_ChatGenAI Integrates generative AI chat into the application. Docs
Pega_Extensions_CheckboxRow A row of checkboxes with optional triggers. Docs
Pega_Extensions_CheckboxTrigger Checkbox that triggers actions on change. Docs
Pega_Extensions_CompareTableLayout Displays data in a comparison table format. Docs
Pega_Extensions_CPQTree Reads the CPQ Tree structure and displays it in Constellation. Docs
Pega_Extensions_DisplayAttachments Renders file attachments with download links. Docs
Pega_Extensions_DisplayPDF Shows PDF documents inline. Docs
Pega_Extensions_DynamicHierarchicalForm Dynamically builds a hierarchical form based on data. Docs
Pega_Extensions_EditableTableLayout Table layout with inline editing capabilities. Docs
Pega_Extensions_FieldGroupAsRow Groups multiple fields into a single row layout. Docs
Pega_Extensions_FormFullWidth Expands a form to full width of container. Docs
Pega_Extensions_FormWithVerticalStepper Vertical Screen flow with navigation Docs
Pega_Extensions_GanttChart Visualizes tasks or events in a Gantt chart. Docs
Pega_Extensions_HierarchicalFormAsTasks Presents hierarchical forms in a task‑list style. Docs
Pega_Extensions_IframeWrapper Embeds external content within an iframe. Docs
Pega_Extensions_ImageCarousel Carousel for images with navigation controls. Docs
Pega_Extensions_ImageMagnify Magnifies images on hover or click. Docs
Pega_Extensions_JapaneseInput Provides Japanese language input support. Docs
Pega_Extensions_JawLayout Displays an interactive jaw like structure. Docs
Pega_Extensions_KanbanBoard Kanban board layout for task management. Docs
Pega_Extensions_Map Displays maps with markers and overlays. Docs
Pega_Extensions_MarkdownInput Text area that supports Markdown formatting. Docs
Pega_Extensions_MaskedInput Input field with masking (e.g., phone, SSN). Docs
Pega_Extensions_Meter Visual meter for displaying progress or value ranges. Docs
Pega_Extensions_NetworkDiagram Graphical network diagram with nodes and links. Docs
Pega_Extensions_OAuthConnect Handles OAuth authentication flows. Docs
Pega_Extensions_PasswordInput Secure password input with strength indicator. Docs
Pega_Extensions_QRCode Generates and scans QR codes. Docs
Pega_Extensions_RangeSlider Slider for selecting a numeric range. Docs
Pega_Extensions_RatingLayout Star or numeric rating component. Docs
Pega_Extensions_Scheduler Scheduling UI for events and appointments. Docs
Pega_Extensions_SecureRichText Rich‑text editor with security controls. Docs
Pega_Extensions_Shortcuts Provides keyboard shortcuts for quick actions. Docs
Pega_Extensions_SignatureCapture Capture user signatures via touch or mouse. Docs
Pega_Extensions_StarRatingInput Input for star‑based ratings. Docs
Pega_Extensions_StatusBadge Badge showing status with color coding. Docs
Pega_Extensions_TaskList Displays a list of tasks with actions. Docs
Pega_Extensions_TrendDisplay Shows trends over time (charts, graphs). Docs
Pega_Extensions_UtilityList Generic list component for utilities. Docs
shared Shared utilities and hooks used by multiple components. N/A

2️⃣ Folder Layout & Naming Convention

Every component lives in its own folder under src/components and follows the Pega_Extensions_<ComponentName> pattern. The folder typically contains:

  • Docs.mdx – Markdown + JSX documentation.
  • config.json – Pega metadata used by Designer.
  • demo.stories.tsx – Storybook demo.
  • demo.test.tsx – Jest + React‑Testing‑Library tests.
  • index.tsx – The React component.
  • styles.ts – Optional styled‑components.
  • localizations.json – (optional) i18n strings.
  • shared/create-nonce – Imported to secure script tags.

Tip: The folder name must match the name and componentKey fields in config.json.

3️⃣ config.json – Pega Blueprint

Key Meaning Typical Value Notes
name Unique identifier "Pega_Extensions_<Name>" Must match folder name
label UI label shown in Designer "<Human readable label>"
description Short description "<Short description>"
organization Owning org "Pega"
version Semantic version "4.0.0"
library Library name "Lib"
allowedApplications Array of Pega apps that can use the component []
componentKey Same as name "Pega_Extensions_<Name>"
type Component type (Field, Template, etc.) "Field"
subtype Sub‑type (e.g., Text, DETAILS) "Text"
properties Array of property objects that describe the UI fields exposed to Designer See component‑specific examples Each object includes name, label, format, and optional defaultValue, source, etc.
defaultConfig Default prop values that Pega will use {"label": "@L $this.label"} Optional
buildDate ISO timestamp of the last build "2025-09-29T17:46:21.831Z"
infinityVersion Pega Infinity version "25.1.0-95"
packageCosmosVersion Cosmos version "8.4.1"

Tip: Keep config.json in sync with the component’s index.tsx – the properties array is what Designer will expose to the user.

4️⃣ index.tsx – The Component Skeleton

import { withConfiguration, Flex, FormControl, FormField, Text } from '@pega/cosmos-react-core';
import { useEffect, useRef, useState } from 'react';
import StyledWrapper from './styles';
import '../shared/create-nonce';

export enum MyComponentProps {
  /* Define any enum‑style props if needed */
}

type MyComponentExtProps = {
  /* Custom props that will be exposed to Designer */
  label: string;
  value: string;
  getPConnect: any;
  readOnly?: boolean;
  testId?: string;
};

export const PegaExtensionsMyComponent = (props: MyComponentExtProps) => {
  const { label, value, getPConnect, readOnly, testId } = props;
  const pConn = getPConnect();
  const actions = pConn.getActionsApi();
  const [internal, setInternal] = useState(value);

  useEffect(() => {
    if (!readOnly) {
      actions.updateFieldValue('myField', internal);
    }
  }, [internal, readOnly, actions]);

  return (
    <Flex container={{ direction: 'column' }}>
      <FormField label={label} testId={testId}>
        <FormControl>{readOnly ? <Text>{internal}</Text> : <StyledWrapper>{/* UI */}</StyledWrapper>}</FormControl>
      </FormField>
    </Flex>
  );
};

export default withConfiguration(PegaExtensionsMyComponent);

5️⃣ styles.ts – Optional Styled‑Components

import styled from 'styled-components';

const StyledWrapper = styled.div`
  /* Example styles */
  display: flex;
  align-items: center;
`;

export default StyledWrapper;

6️⃣ Docs.mdx – Documentation for Designers

import { Meta, Canvas, ArgsTable } from '@storybook/addon-docs';

<Meta title='Fields/MyComponent' />

# MyComponent

This component renders a custom UI and synchronizes with Pega state.

## Props

<ArgsTable story='Primary' />

## Demo

<Canvas>
  <Story name='Primary' />
</Canvas>

7️⃣ demo.stories.tsx – Storybook Story

import type { StoryObj } from '@storybook/react-webpack5';
import { PegaExtensionsMyComponent, type PegaExtensionsMyComponentProps } from './index';

export default {
  title: 'Fields/MyComponent',
  argTypes: {
    getPConnect: { table: { disable: true } },
  },
  component: PegaExtensionsMyComponent,
} as const;

const Template: StoryObj<PegaExtensionsMyComponentProps> = (args) => <PegaExtensionsMyComponent {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  label: 'Demo Label',
  value: 'Initial value',
  getPConnect: () => ({
    /* Mocked PConnect */
  }),
};

8️⃣ demo.test.tsx – Jest + React‑Testing‑Library

import { render, screen } from '@testing-library/react';
import { PegaExtensionsMyComponent } from './index';

const mockPConnect = {
  getActionsApi: () => ({ updateFieldValue: jest.fn() }),
  getStateProps: () => ({ value: 'myField' }),
  getValue: jest.fn(),
};

test('renders label and value', () => {
  render(<PegaExtensionsMyComponent label='Test' value='Hello' getPConnect={() => mockPConnect} />);
  expect(screen.getByText('Test')).toBeInTheDocument();
  expect(screen.getByText('Hello')).toBeInTheDocument();
});

9️⃣ localizations.json – Optional i18n

{
  "en": {
    "myLabel": "My Label"
  },
  "es": {
    "myLabel": "Mi Etiqueta"
  }
}

🔧 Build, Test & Deploy

# Format and lint
npm run lint

# Type‑check
npm run typecheck

# Run tests
npm test

# Build component bundle
npm run build

# Start Storybook
npm run storybook

📚 Further Reading

Happy building!