@pega/custom-dx-components 0.25.53 → 0.25.55

package/README.md

@@ -4,6 +4,24 @@
 
 This project provides you with an environment to extend Constellation by giving you tools to create and publish custom components that are not available from the Constellation installation.
 
+## Before you begin
+Review the following checklist before you create a Constellation DX component:
+
+## Design considerations
+Involve an Experience Designer in your process. This will help you determine the exact issue to be resolved. For more information on the role of an Experience Designer, see **Experience Designer**[here](https://community.pega.com/roles/experience-designer).
+
+## The Experience Designer must meet the following requirements:
+Must have a background in UI and UX design.
+Must understand Pega's best practices for design. For more information, see **Best practices for designing with the Constellation design system**[here](https://design.pega.com/design/getting-started/).
+
+## Functionality considerations
+Check if an existing component in App Studio contains the features you need. If not, check for existing components that contain similar features.
+Connect with Pega Support to find out if a component containing a similar feature will be included in the next release. If yes, assess if you can wait for the next release.
+
+## Maintenance considerations
+Ensure you have the bandwidth to maintain the Constellation DX component and keep it up-to-date with every release of Pega Infinity. Evaluate if doing this might prevent you from upgrading to future releases of Pega Infinity.
+Evaluate if you are able to meet the compliance standards for data privacy and accessibility for Constellation DX components. Note that not meeting these standards might lead to legal compliance issues.
+
 ## Prerequisites
 
 Ensure you have access to the following in your system:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pega/custom-dx-components",
-  "version": "0.25.53",
+  "version": "0.25.55",
   "description": "Utility for building custom UI components",
   "bin": "./bin/index.js",
   "keywords": [
@@ -25,7 +25,7 @@
     "@babel/plugin-transform-class-properties": "^7.27.1",
     "@babel/preset-react": "^7.27.1",
     "@pega/auth": "^0.2.27",
-    "@pega/constellation-dx-components-build-utils": "^2.0.7",
+    "@pega/constellation-dx-components-build-utils": "^2.0.8",
     "@pega/inquirer-fuzzy-path": "^3.0.0",
     "ajv": "^8.17.1",
     "ajv-keywords": "^5.1.0",

package/src/tasks/create/templates/Launchpad/Field/Text-Phone/config.json.mustache

@@ -0,0 +1,146 @@
+{
+  "name": "{{COMPONENT_KEY}}",
+  "label": "{{COMPONENT_LABEL}}",
+  "description": "{{DESCRIPTION}}",
+  "organization": "{{ORGANIZATION}}",
+  "version": "{{VERSION}}",
+  "library": "{{LIBRARY}}",
+  "componentKey": "{{COMPONENT_KEY}}",
+  "type": "{{TYPE}}",
+  "subtype": {{{SUB_TYPE}}},
+  "subtypeLabel": "{{SUB_TYPE_LABEL}}",
+  "icon": "images/pz-phone-active.svg",
+  "properties": [
+    {
+      "name": "label",
+      "label": "Field label",
+      "format": "TEXT",
+      "required": true
+    },
+    {
+      "name": "labelOption",
+      "label": "Field label",
+      "format": "SELECT",
+      "defaultValue": "custom",
+      "visibility": "@PLATFORMNAME != 'launchpad'",
+      "source": [
+        {
+          "key": "default",
+          "value": "Default"
+        },
+        {
+          "key": "custom",
+          "value": "Custom"
+        }
+      ]
+    },
+    {
+      "name": "label",
+      "label": "Custom field label",
+      "format": "VALUEINPUT",
+      "required": true,
+      "ruleType": "Paragraph",
+      "visibility": "@PLATFORMNAME != 'launchpad'"
+    },
+    {
+      "name": "readOnly",
+      "label": "Edit mode",
+      "format": "READONLY"
+    },
+    {
+      "name": "showCountryCode",
+      "label": "Show Country Code",
+      "format": "BOOLEAN",
+      "defaultValue": true
+    },
+    {
+      "label": "Column settings",
+      "format": "GROUP",
+      "visibility": "@VIEWTYPE == 'MultiRecordDisplayAsTable'",
+      "properties": [
+        {
+          "name": "columnWidth",
+          "label": "Column width",
+          "format": "SELECT",
+          "source": [
+            {
+              "key": "auto",
+              "value": "Auto"
+            },
+            {
+              "key": "custom",
+              "value": "Custom"
+            }
+          ]
+        },
+        {
+          "name": "width",
+          "label": "Width (px)",
+          "format": "NUMBER",
+          "visibility": "$this.columnWidth == 'custom'"
+        }
+      ]
+    },
+    {
+      "label": "Input settings",
+      "format": "GROUP",
+      "visibility": "(!readOnly = true)",
+      "properties": [
+        {
+          "name": "placeholder",
+          "label": "Placeholder",
+          "format": "TEXT"
+        },
+        {
+          "name": "helperText",
+          "label": "Helper text",
+          "format": "TEXT"
+        }
+      ]
+    },
+    {
+      "label": "Conditions",
+      "format": "GROUP",
+      "properties": [
+        {
+          "name": "required",
+          "label": "Required",
+          "format": "REQUIRED",
+          "visibility": "(!readOnly = true)"
+        },
+        {
+          "name": "disabled",
+          "label": "Disabled",
+          "format": "DISABLED",
+          "visibility": "(!readOnly = true)"
+        },
+        {
+          "name": "visibility",
+          "label": "Visibility",
+          "format": "VISIBILITY"
+        }
+      ]
+    },
+    {
+      "label": "Advanced",
+      "format": "GROUP",
+      "collapsible": true,
+      "properties": [
+        {
+          "name": "testId",
+          "label": "Test ID",
+          "format": "TEXT",
+          "ignorePattern": "[^-_\\p{N}\\p{L}]",
+          "includeAnnotations": false
+        }
+      ]
+    }
+  ],
+  "defaultConfig": {
+    "label": "@L $this.label",
+    "datasource": {},
+    "detailFVLItem": true,
+    "isFormWidth" : false,
+    "isContainerWidth" : false
+  }
+}

package/src/tasks/create/templates/Launchpad/Field/Text-Phone/demo.stories.tsx.mustache

@@ -0,0 +1,61 @@
+/* eslint-disable react/jsx-no-useless-fragment */
+import type { Meta, StoryObj } from '@storybook/react';
+
+import {{COMPONENT_CLASS_NAME}} from './index';
+import { stateProps, configProps } from './mock';
+
+const meta: Meta<typeof {{COMPONENT_CLASS_NAME}}> = {
+  title: '{{COMPONENT_CLASS_NAME}}',
+  component: {{COMPONENT_CLASS_NAME}},
+  excludeStories: /.*Data$/
+};
+
+export default meta;
+type Story = StoryObj<typeof {{COMPONENT_CLASS_NAME}}>;
+
+export const Base{{COMPONENT_CLASS_NAME}}: Story = (args: any) => {
+
+  const props = {
+    value: configProps.value,
+    hasSuggestions: configProps.hasSuggestions,
+    getPConnect: () => {
+      return {
+        getStateProps: () => {
+          return stateProps;
+        },
+        getActionsApi: () => {
+          return {
+            updateFieldValue: () => {/* nothing */},
+            triggerFieldChange: () => {/* nothing */}
+          };
+        },
+        ignoreSuggestion: () => {/* nothing */},
+        acceptSuggestion: () => {/* nothing */},
+        setInheritedProps: () => {/* nothing */},
+        resolveConfigProps: () => {/* nothing */}
+      };
+    }
+  };
+
+  return (
+    <>
+      <{{COMPONENT_CLASS_NAME}} {...props} {...args} />
+    </>
+  );
+};
+
+Base{{COMPONENT_CLASS_NAME}}.args = {
+  datasource: configProps.datasource,
+  label: configProps.label,
+  helperText: configProps.helperText,
+  placeholder: configProps.placeholder,
+  testId: configProps.testId,
+  readOnly: configProps.readOnly,
+  disabled: configProps.disabled,
+  required: configProps.required,
+  status: configProps.status,
+  hideLabel: configProps.hideLabel,
+  displayMode: configProps.displayMode,
+  variant: configProps.variant,
+  validatemessage: configProps.validatemessage
+};

package/src/tasks/create/templates/Launchpad/Field/Text-Phone/demo.test.tsx.mustache

@@ -0,0 +1,23 @@
+// import { expect, test } from '@jest/globals';
+import { render, screen } from '@testing-library/react';
+import { composeStories } from '@storybook/react';
+import '@testing-library/jest-dom';
+
+import * as DemoStories from './demo.stories';
+
+const { Base{{COMPONENT_CLASS_NAME}} } = composeStories(DemoStories);
+
+test('renders {{COMPONENT_CLASS_NAME}}', async () => {
+  render(<Base{{COMPONENT_CLASS_NAME}} />);
+  expect(await screen.findByText('Phone Sample')).toBeVisible();
+  expect(await screen.findByText('Phone Helper Text')).toBeVisible();
+
+
+  const phoneElement = (screen.getByTestId('phone-12345678') as HTMLInputElement);
+  expect(phoneElement.value).toBe('');
+
+  expect(phoneElement).toHaveAttribute('placeholder', 'Phone Placeholder');
+
+  const countryElement = (screen.getByTestId(":phone-input:country-code") as HTMLSelectElement);
+  expect(countryElement.value).toContain("+1");
+});

package/src/tasks/create/templates/Launchpad/Field/Text-Phone/event-utils.ts.mustache

@@ -0,0 +1,18 @@
+const handleEvent = (actions: any, eventType: string, propName: string, value: string | number) => {
+  switch (eventType) {
+    case 'change':
+      actions.updateFieldValue(propName, value);
+      break;
+    case 'blur':
+      actions.triggerFieldChange(propName, value);
+      break;
+    case 'changeNblur':
+      actions.updateFieldValue(propName, value);
+      actions.triggerFieldChange(propName, value);
+      break;
+    default:
+      break;
+  }
+};
+
+export default handleEvent;

package/src/tasks/create/templates/Launchpad/Field/Text-Phone/index.tsx.mustache

@@ -0,0 +1,246 @@
+import { useState, useEffect, useRef } from 'react';
+import {
+  PhoneInput as CosmosPhone,
+  getPhoneNumberParts,
+  PhoneDisplay,
+  FieldValueList,
+  Text,
+  EmailDisplay,
+  URLDisplay,
+  withConfiguration
+} from '@pega/cosmos-react-core';
+import type { PConnFieldProps } from './PConnProps';
+import './create-nonce';
+
+// includes in bundle
+import handleEvent from "./event-utils";
+import { suggestionsHandler } from './suggestions-handler';
+
+import Styled{{COMPONENT_CLASS_NAME}}Wrapper from './styles';
+
+// interface for props
+interface {{COMPONENT_CLASS_NAME}}Props extends PConnFieldProps {
+  // If any, enter additional props that only exist on TextInput here
+  displayAsStatus?: boolean;
+  isTableFormatter?: boolean;
+  hasSuggestions?: boolean;
+  variant?: any;
+  formatter: string;
+  datasource: any;
+  showCountryCode: boolean;
+}
+
+// interface for StateProps object
+interface StateProps {
+  value: string;
+  hasSuggestions: boolean;
+}
+
+export const formatExists = (formatterVal: string) => {
+    const formatterValues = [
+      "TextInput",
+      "WorkStatus",
+      "RichText",
+      "Email",
+      "Phone",
+      "URL",
+      "Operator"
+    ];
+    let isformatter = false;
+    if (formatterValues.includes(formatterVal)) {
+      isformatter = true;
+    }
+    return isformatter;
+  };
+
+
+export const textFormatter = (formatter: string, value: any) => {
+  let displayComponent:any = null;
+  switch(formatter){
+    case "TextInput" : {
+      displayComponent = value;
+      break;
+    }
+    case "Email" : {
+      displayComponent = (<EmailDisplay value={value} displayText={value} variant="link" />);
+      break;
+    }
+    case "Phone" : {
+      displayComponent = (<PhoneDisplay value={value} variant="link" />);
+      break;
+    }
+    case "URL" : {
+      displayComponent = (<URLDisplay target="_blank" value={value} displayText={value} variant="link" />);
+      break;
+    }
+    // no default
+  }
+  return displayComponent;
+};
+
+
+
+// Duplicated runtime code from Constellation Design System Component
+
+// props passed in combination of props from property panel (config.json) and run time props from Constellation
+// any default values in config.pros should be set in defaultProps at bottom of this file
+function {{COMPONENT_CLASS_NAME}}(props: {{COMPONENT_CLASS_NAME}}Props) {
+  const {
+    getPConnect,
+    value,
+    showCountryCode = true,
+    placeholder,
+    validatemessage,
+    label,
+    hideLabel = false,
+    helperText,
+    datasource = [],
+    testId,
+    displayMode,
+    additionalProps = {},
+    variant = 'inline',
+    isTableFormatter = false,
+    hasSuggestions = false
+  } = props;
+  const { formatter } = props;
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const stateProps = pConn.getStateProps() as StateProps;
+  const propName: string = stateProps.value;
+  const hasValueChange = useRef(false);
+
+  let callingCodesList: Array<any>  = [];
+  if (datasource?.source?.length > 0) {
+    datasource.source.forEach((element: { value: any; }) => {
+      callingCodesList.push(element.value);
+    });
+  } else {
+    callingCodesList = ['+1']; // if no datasource is present we default to show only US country code
+  }
+
+  // BUG-547602: Temporary type coercion for 8.5 until DXAPIs are enhanced to pass original pxViewMetadata JSON, respecting boolean primitives
+  let { readOnly = false, required = false, disabled = false } = props;
+  [readOnly, required, disabled] = [readOnly, required, disabled].map(
+    (prop) => prop === true || (typeof prop === 'string' && prop === 'true')
+  );
+
+  const [inputValue, setInputValue] = useState(value);
+  useEffect(() => setInputValue(value), [value]);
+
+  const [status, setStatus] = useState(hasSuggestions ? 'pending' : undefined);
+  useEffect(() => {
+    if (validatemessage !== '') {
+      setStatus('error');
+    }
+    if (hasSuggestions) {
+      setStatus('pending');
+    } else if (!hasSuggestions && status !== 'success') {
+      setStatus(validatemessage !== '' ? 'error' : undefined);
+    }
+  }, [validatemessage, hasSuggestions, status]);
+
+  // function to exclude country code from phone number
+  function getPhoneNumberAlone(phoneNumber: string) {
+    const phoneNumberParts = getPhoneNumberParts(phoneNumber, callingCodesList);
+    return phoneNumberParts && phoneNumberParts[1];
+  }
+
+  function handleChangeBlur(enteredValue: string, eventType: any) {
+    if (!getPhoneNumberAlone(enteredValue)) {
+      enteredValue = '';
+    }
+    handleEvent(actions, eventType, propName, enteredValue);
+  }
+
+  let displayComp: any = null;
+  if (displayMode) {
+    displayComp = <PhoneDisplay value={value} variant='link' />;
+  }
+
+  if (displayMode === 'LABELS_LEFT' || displayMode === 'DISPLAY_ONLY') {
+    if (isTableFormatter && formatExists(formatter)) {
+      displayComp = textFormatter(formatter, value);
+    }
+    return displayMode === 'DISPLAY_ONLY' ? (
+      <Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+      {displayComp}
+      </Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+    ) : (
+      <Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+      <FieldValueList
+        variant={hideLabel ? 'stacked' : variant}
+        data-testid={testId}
+        fields={[{ id: '1', name: hideLabel ? '' : label, value: displayComp }]}
+      />
+      </Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+    );
+  }
+
+  if (displayMode === 'STACKED_LARGE_VAL') {
+    return (
+      <Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+      <FieldValueList
+        variant='stacked'
+        data-testid={testId}
+        fields={[
+          {
+            id: '2',
+            name: hideLabel ? '' : label,
+            value: (
+              <Text variant='h1' as='span'>
+                {displayComp}
+              </Text>
+            )
+          }
+        ]}
+      />
+      </Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+    );
+  }
+
+  const onResolveSuggestionHandler = (accepted: boolean) => {
+    suggestionsHandler(accepted, pConn, setStatus);
+  };
+
+  return (
+    <Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+    <CosmosPhone
+      {...additionalProps}
+      label={label}
+      info={validatemessage || helperText}
+      value={inputValue}
+      labelHidden={hideLabel}
+      status={status}
+      showCountryCode={showCountryCode}
+      callingCodesList={callingCodesList}
+      placeholder={placeholder}
+      disabled={disabled}
+      readOnly={readOnly}
+      required={required}
+      data-testid={testId}
+      onChange={(enteredValue: any) => {
+        if (hasSuggestions) {
+          setStatus('');
+        }
+        setInputValue(enteredValue);
+        if (value !== enteredValue) {
+          handleEvent(actions, 'change', propName, enteredValue);
+        }
+        hasValueChange.current = true;
+      }}
+      onBlur={(enteredValue: any) => {
+        if (!value || hasValueChange.current) {
+          handleChangeBlur(enteredValue, 'blur');
+          if (hasSuggestions) {
+            pConn.ignoreSuggestion('');
+          }
+          hasValueChange.current = false;
+        }
+      }}
+      onResolveSuggestion={onResolveSuggestionHandler}
+    />
+    </Styled{{COMPONENT_CLASS_NAME}}Wrapper>
+  );
+}
+
+export default withConfiguration({{COMPONENT_CLASS_NAME}});

package/src/tasks/create/templates/Launchpad/Field/Text-Phone/mock.ts.mustache

@@ -0,0 +1,40 @@
+export const configProps = {
+  value: '',
+  label: 'Phone Sample',
+  datasource: {
+    source: [
+      {
+        value: '+1'
+      },
+      {
+        value: '+91'
+      },
+      {
+        value: '+48'
+      },
+      {
+        value: '+44'
+      }
+    ],
+    fields: {}
+  },
+  showCountryCode: true,
+  placeholder: 'Phone Placeholder',
+  helperText: 'Phone Helper Text',
+  testId: 'phone-12345678',
+  hasSuggestions: false,
+  displayMode: '',
+  variant: '',
+  hideLabel: false,
+  readOnly: false,
+  required: false,
+  disabled: false,
+  status: '',
+  validatemessage: ''
+};
+
+export const stateProps = {
+  value: '.PhoneSample',
+  datasource: {},
+  hasSuggestions: false
+};

package/src/tasks/create/templates/Launchpad/Field/Text-Phone/styles.ts.mustache

@@ -0,0 +1,8 @@
+// individual style, comment out above, and uncomment here and add styles
+import styled, { css } from 'styled-components';
+
+export default styled.div(() => {
+  return css`
+    margin: 0px 0;
+  `;
+});

package/src/tasks/create/templates/Launchpad/Template/FORM/DefaultForm.svg

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="100px" height="70px" viewBox="0 0 100 70" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>2 col  copy</title>
+    <g id="Views" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="Template-icons" transform="translate(-320.000000, -925.000000)">
+            <g id="2-col--copy" transform="translate(320.000000, 925.000000)">
+                <rect id="bg" stroke="#A5A8BC" stroke-width="0.5" fill="#E7E9EB" x="0.25" y="0.25" width="99.5" height="69.5"></rect>
+                <g id="white" transform="translate(3.000000, 3.000000)" fill="#FFFFFF">
+                    <rect id="Rectangle" x="0" y="0" width="94" height="66.5"></rect>
+                </g>
+                <g id="gray-copy-2" transform="translate(6.000000, 6.000000)" fill="#8084A7">
+                    <rect id="Rectangle" x="0" y="-2.84217094e-14" width="42" height="11.8"></rect>
+                    <rect id="Rectangle" x="46" y="-2.84217094e-14" width="42" height="11.8"></rect>
+                    <rect id="Rectangle-Copy-5" x="0" y="16" width="42" height="11.8"></rect>
+                    <rect id="Rectangle-Copy-3" x="46" y="16" width="42" height="11.8"></rect>
+                    <rect id="Rectangle-Copy-15" x="0" y="32" width="42" height="11.8"></rect>
+                    <rect id="Rectangle-Copy-14" x="46" y="32" width="42" height="11.8"></rect>
+                    <rect id="Rectangle-Copy-17" x="0" y="48" width="42" height="11.8"></rect>
+                    <rect id="Rectangle-Copy-16" x="46" y="48" width="42" height="11.8"></rect>
+                </g>
+                <g id="Group-7" transform="translate(28.000000, 11.000000)">
+                    <path id="Line-12-Copy" d="M35.1666667,42.75 L47.1666667,48.5 L35.1666667,54.25 L35.166,49.25 L-0.25,49.25 L-0.25,47.75 L35.166,47.75 L35.1666667,42.75 Z" fill="#1E1F27" fill-rule="nonzero"></path>
+                    <line x1="0.5" y1="48.5" x2="43.5" y2="32.5" id="Line" stroke="#1E1F27" stroke-width="1.5" stroke-linecap="square"></line>
+                    <line x1="43.5" y1="32.5" x2="1.5" y2="32.5" id="Line-2" stroke="#1E1F27" stroke-width="1.5" stroke-linecap="square"></line>
+                </g>
+            </g>
+        </g>
+    </g>
+</svg>

package/src/tasks/create/templates/Launchpad/Template/FORM/DetailsRender.tsx.mustache

@@ -0,0 +1,59 @@
+import { Fragment, type ReactElement } from 'react';
+import { FieldValueList } from '@pega/cosmos-react-core';
+
+interface DetailsRenderProps {
+  children?: never;
+  child: NonNullable<ReactElement>;
+}
+
+const DetailsRender = (props: DetailsRenderProps) => {
+  const { child } = props;
+
+  const kids = child.props.getPConnect().getChildren();
+
+  const displayCompArr: ReactElement[] = [];
+
+  Object.values(kids).forEach((value: any) => {
+    const { type } = value.getPConnect().getRawMetadata();
+    const { hideLabel, variant, testId, label } = value
+      .getPConnect()
+      .resolveConfigProps(value.getPConnect().getConfigProps());
+
+    let displayComp;
+    const key = JSON.stringify(value.getPConnect());
+
+    if (type === 'reference') {
+      const refElement = value.getPConnect().getComponent();
+
+      displayCompArr.push(refElement);
+    } else {
+      const element = value.getPConnect().getComponent();
+      const displayEl = <Fragment key={key}>{element}</Fragment>;
+
+      const fvlStyle = {
+        myColGap: {
+          columnGap: '0',
+          marginLineStart: 0
+        }
+      };
+
+      // const myEl = <div>boo</div>;
+      displayComp = (
+        <Fragment key={key}>
+          <FieldValueList
+            style={fvlStyle.myColGap}
+            variant={hideLabel ? 'stacked' : variant}
+            data-testid={testId}
+            fields={[{ id: '1', name: hideLabel ? '' : label, value: displayEl }]}
+          />
+        </Fragment>
+      );
+
+      displayCompArr.push(displayComp);
+    }
+  });
+
+  return <>{displayCompArr}</>;
+};
+
+export default DetailsRender;