@pega/custom-dx-components 26.1.11 → 26.1.12-alpha.0.2

package/src/ai/project/.claude/skills/create-dx-component/references/choosing-type-and-subtype.md

@@ -0,0 +1,79 @@
+# Choosing a Component Type and Subtype
+
+Use this when the request is not a plain "make a <subtype> field": a custom control (a star rating, a signature pad), a block you cannot name a subtype for (a kanban board), or something that may not be a custom component at all. The CLI accepts a fixed set of subtypes, and `validate-schema` rejects any other, so every idea has to land on one of them or be declared out of scope. Never invent a subtype.
+
+## 1. Fit check
+
+A custom DX component is one of four things:
+
+| Type | It is |
+| --- | --- |
+| Field | One control bound to **one case property** |
+| Widget | A standalone block that loads and shows its own data |
+| Template | A layout that arranges child views and fields |
+| Presentation | A replacement for the whole case view page |
+
+If the request is none of these, say so plainly, name the closest option, and let the user decide. Do not stretch a type to fit. Examples that do not fit as stated:
+
+- Changing the app shell, navigation, theme or portal frame.
+- Adding or intercepting the buttons and flow actions of an assignment.
+- Business logic, validation rules or data models. Those live in the Pega application, not in a DX component.
+- A control that stores a **list** of values or **several properties** at once. No Field subtype binds more than one scalar property. Offer instead: a Template that arranges existing fields; a Widget that writes back to the property (confirm the stored shape with the app designer and flag it as a risk); or a delimited string in a Text field if the user accepts that.
+
+If you are unsure whether something is possible on the platform, say that you are unsure instead of building a guess.
+
+## 2. Pick the type
+
+Ask in this order and stop at the first yes:
+
+1. Does it replace how the whole case view page is rendered? **Presentation** (`CASEVIEW` or `WSSCASEVIEW`).
+2. Does it edit or show **one** case property? **Field**.
+3. Does its main job arrange other components that the app designer places inside it? **Template**.
+4. Does it show its own data (chart, list, KPI, board, timeline)? **Widget**.
+
+A read-only badge, pill, icon or formatted value bound to a property is a Field that handles `DISPLAY_ONLY`. If it loads its own data instead, it is a Widget.
+
+## 3. Pick the subtype
+
+**Field: choose by the type of the stored value, not by how the control looks.** The control can be anything Cosmos or the browser can render.
+
+| Stored value | Subtype |
+| --- | --- |
+| Short or free text | `Text`, `Text-Input` (single line), `Text-Paragraph` (multi-line) |
+| Email, phone, web address | `Text-Email`, `Text-Phone`, `Text-URL`; `Icon-Button-URL` for a link shown as an icon button |
+| Whole number | `Integer` |
+| Fractional number | `Decimal`; `Decimal-Currency` for money; `Decimal-Percentage` for a percent |
+| True or false | `Boolean` |
+| Date, date and time, time of day | `Date`, `DateTime`, `TimeOfDay` |
+| One choice from a list | `Picklist` (dropdown), `Picklist-RadioButtons`, `Picklist-Autocomplete` (searchable) |
+
+**Template:** `FORM` (editable fields), `DETAILS` (read-only label/value pairs), `PAGE` (whole-page regions). `FORM-region` and `DETAILS-region` are the multi-region variants. `PAGE` is the template to use for an app-level layout with named regions.
+
+**Widget:** `CASE` when it belongs inside a case view and uses the current case, `PAGE` when it sits on a portal page or dashboard with no case, and, if the same widget must work in both, the `config.json` subtype can be the array `["PAGE", "CASE"]` (shown as "PAGE & CASE"). The `create` argument for that combination is not documented in [cli-workflow.md](./cli-workflow.md), so pick `CASE` or `PAGE` unless the user needs both, and then check the CLI help first.
+
+**Presentation:** `CASEVIEW`, or `WSSCASEVIEW` for the Web Self Service portal.
+
+## 4. Worked examples
+
+| The user wants | Type and subtype | Notes |
+| --- | --- | --- |
+| A star rating (1 to 5) | Field `Integer` | Custom control over a whole number. The Cosmos `Rating` component in the build checked takes `value`, `maxRating` and `readOnly` and has no change callback, so use it for the `DISPLAY_ONLY` view and build the editable control from a Cosmos radio group so it stays keyboard and screen-reader operable. Check `Rating.d.ts` in the installed version |
+| A slider for a quantity | Field `Integer` | Cosmos has a slider; check its `.d.ts` first |
+| A status pill or badge for a property | Field `Text` with `DISPLAY_ONLY` | See [the status badge recipe](../cookbooks/status-badge-field.md) |
+| A color picker | Field `Text` | Store a hex string such as `#1A2B3C` |
+| A signature pad | Field `Text-Paragraph` | Stores a data URL, which can be large; confirm the property's size limit with the user. Try the browser canvas before asking to add a library |
+| A time picker | Field `TimeOfDay` | |
+| A searchable customer lookup | Field `Picklist-Autocomplete` | The options come from the property's configured source |
+| Tag input or multi-select | Not a Field | See the fit check: it stores a list |
+| An address block | Not a Field | It binds several properties. Offer a Template that arranges the existing address fields |
+| A kanban board, timeline, chart, KPI tile, map, org chart | Widget `CASE` or `PAGE` | `CASE` if it shows the current case's data, otherwise `PAGE`. Data comes from a data page. Check Cosmos for a ready component before proposing a charting or map library |
+| A tabbed or stepper layout of fields | Template `FORM-region` or `PAGE` | One region per tab or step. Use Cosmos `Tabs`; editable steps must all stay mounted so validation sees every field (see [template-patterns.md](./template-patterns.md)) |
+| A read-only summary panel | Template `DETAILS` | Must force read-only on its children |
+| A sidebar layout or dashboard grid | Template `PAGE` | Regions `A` and `B` |
+| A custom case header with tabs on the left | Presentation `CASEVIEW` | Props only; no PCore or PConnect |
+
+## 5. Decide, then say what you decided
+
+- If two types or subtypes both fit, take the narrowest, state the assumption in one sentence, and ask once. The ambiguity rule in [AGENTS.md](../../../../AGENTS.md) applies.
+- Say which subtype you chose and **why** (for a Field, the stored value type). The user can then correct a wrong storage assumption before any code exists.
+- If the idea needs a third-party library, first check whether Cosmos or the browser already does it. Propose a library only when neither does, and follow the consent rule in [AGENTS.md](../../../../AGENTS.md).

package/src/ai/project/.claude/skills/create-dx-component/references/cli-workflow.md

@@ -0,0 +1,125 @@
+# Custom Component Project Workflow (CLI, Build, Test)
+
+> Part of the [create-dx-component skill](../SKILL.md). PCore/PConnect signatures are in the [API catalog](./pcore-pconnect-apis.md).
+
+This file explains how a custom component project is laid out and which commands an AI assistant can run **without interactive prompts** to scaffold, check and build components. Every command form below was run against a generated project.
+
+## Project layout
+
+```text
+<project>/
+  tasks.config.json            # CLI configuration (library, version, server settings)
+  src/components/
+    shared/                    # PConnProps.d.ts, create-nonce.ts (shared by library components)
+    <Org>_<Library>_<Name>/    # one folder per component
+      config.json              # design-time definition: properties, defaults
+      index.tsx                # the React component
+      styles.ts                # styled-components wrapper
+      mock.ts                  # sample props/state props for stories and tests
+      demo.stories.tsx         # Storybook story (supplies a mocked getPConnect)
+      demo.test.tsx            # Jest test built on the story
+  src/globals.d.ts             # declares the global `PCore` type
+  setupTests.ts, jest.config.cjs, tsconfig.json, eslint.config.mjs
+```
+
+Some component types add helper files (for example `DetailsRender.tsx`, `utils.ts`, `localizations.json`).
+
+## Library mode: create a library first
+
+New projects run in **library mode**. Until a library exists, almost every command fails with a message to run `createLib`. Create one once per project:
+
+```bash
+npm run createLib -- <LibraryName> <version> Y Current
+# example
+npm run createLib -- Lib 1.0.0 Y Current
+```
+
+Arguments: library name (alphanumeric, starts with a letter), semver version, `Y`/`N` for a permanent build (library mode always treats it as permanent), and `Current` or `Original` (only relevant when archives already exist).
+
+## One-command check
+
+`node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` runs the whole loop below for one component and prints a PASS/FAIL/WARN/NOT RUN table. The schema check, `tsc`, ESLint and Jest run in parallel; `tsc` covers only this component, `src/components/shared/` and the global declarations, and is incremental. The build starts only when the schema and ESLint checks pass, because it repeats both and would fail anyway.
+
+While fixing failures, rerun it with `--no-build` (or the single command for the failing row). Run it once without `--no-build` for the final table.
+
+## Non-interactive commands
+
+The `npm run` scripts forward everything after `--` to the CLI. Without arguments each command prompts interactively, which an AI assistant cannot answer, so **always pass the arguments**.
+
+| Goal                      | Command                                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Create a library          | `npm run createLib -- <Library> <version> Y Current`                                                          |
+| Scaffold a component      | `npm run create -- <type> <subtype> <Name> "<Label>" <version> <Library> "<description>" <Organization>`      |
+| Validate `config.json`    | `npm run validate-schema -- <Org>_<Library>_<Name>`                                                           |
+| Lint, validate and bundle | `npm run buildComponent -- <Org>_<Library>_<Name> N N` (the last two are source map `Y/N` and dev build `Y/N`) |
+| Build every component     | `npm run buildAllComponents`                                                                                  |
+| List components           | `npm run list` (safe). `npm run listLib` prompts and crashes when run without a terminal                       |
+| Aliases                   | `npm run validate` is `buildComponent` and `npm run validateAll` is `buildAllComponents`; they take the same arguments |
+
+Scaffold example:
+
+```bash
+npm run create -- Field Text-Email ContactEmail "Contact email" 1.0.0 Lib "Email field" Acme
+# creates src/components/Acme_Lib_ContactEmail
+```
+
+Valid `<type>` and `<subtype>` values:
+
+| Type           | Subtypes                                                                                                                                                                      |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Field`        | `Text`, `Text-Input`, `Text-Paragraph`, `Text-Email`, `Text-Phone`, `Text-URL`, `Icon-Button-URL`, `Integer`, `Decimal`, `Decimal-Currency`, `Decimal-Percentage`, `Boolean`, `Date`, `DateTime`, `TimeOfDay`, `Picklist`, `Picklist-Autocomplete`, `Picklist-RadioButtons` |
+| `Template`     | `DETAILS`, `DETAILS-region`, `FORM`, `FORM-region`, `PAGE`                                                                                                                    |
+| `Widget`       | `CASE`, `PAGE`                                                                                                                                                                |
+| `Presentation` | `CASEVIEW`, `WSSCASEVIEW`                                                                                                                                                     |
+
+Use these values exactly, including casing (for example `TimeOfDay`, not `TimeofDay`). With arguments supplied, `create` does not validate the subtype up front: an unknown subtype either fails with a missing-template error or generates a `config.json` that then fails `validate-schema` with `data/subtype must be equal to one of the allowed values`. The authoritative list is `COMPONENT_SCHEMA` in the installed `@pega/custom-dx-components` package.
+
+## Naming rules
+
+- The component key is `<Organization>_<Library>_<Name>`: exactly three alphanumeric segments separated by underscores. `config.json` `name` and `componentKey` must match this pattern (`validate-schema` enforces it).
+- `<Name>`, `<Library>` and `<Organization>` must be alphanumeric, start with a letter and contain no spaces.
+- The component's React function name is the PascalCase form of the key (for example `Acme_Lib_ContactEmail` becomes `AcmeLibContactEmail`).
+- Keep names short. The CLI rejects names that exceed the length limit for the server.
+
+## Check loop (run after every change)
+
+Run from the project root, in this order, and fix failures before moving on:
+
+```bash
+npx tsc --noEmit 2>&1 | grep -v "demo.stories.tsx"   # types in your own files
+npm test                                              # Jest (coverage thresholds apply)
+npm run lint                                          # ESLint
+npm run validate-schema -- <Org>_<Library>_<Name>     # config.json against the schema
+npm run buildComponent -- <Org>_<Library>_<Name> N N  # lint + validate + bundle
+```
+
+Notes:
+
+- `npm run lint` lints `src/` and the project config; the `.claude/` skill assets are ignored.
+- `npm test` and the build create `coverage/` and `dist/` in the project root. Both are git-ignored in projects made by `init`.
+- Freshly scaffolded Widget, Template and Presentation `demo.stories.tsx` files can produce `tsc` errors such as `Property 'PCore' does not exist on type 'Window'`. Stories are excluded from lint and the bundle, so filter them out as shown. Do not edit those scaffolded stories only to silence the error. Any error in `index.tsx`, `config.json` or your own files is real and must be fixed.
+- `npm test` runs every `demo.test.tsx`. To run one, use `npx jest <path>` (add `--coverage=false` to skip the coverage thresholds).
+- `buildComponent` runs schema validation, then lint, then the bundle. A lint failure stops the build before bundling.
+- Storybook (`npm run startStorybook`) is a long-running dev server. Do not start it from an automated check loop unless the user asks.
+
+## Commands that need the user
+
+Do not run these unless the user explicitly asks, because they need credentials, a Pega server, or change or delete data:
+
+- `authenticate`, `publish`, `publishAll`, `publishLibVersion`, `exportRC`: use the server settings and credentials in `tasks.config.json`.
+- `delete`, `deleteAll`, `deleteLib`, `deletePublishedLib`, `deleteLibVersion`, `restoreLibVersion`: destructive.
+- `rename`, `move`, `switchLib`, `createLibVersion`, `importLibVersion`: change the project structure or library state.
+
+Never write secrets (client secrets, passwords, tokens) into `tasks.config.json` or source files, and never commit the `keys/` directory contents or `.npmrc` credentials.
+
+## Troubleshooting
+
+| Symptom                                                                          | Likely cause and fix                                                                                           |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| "All commands will NOT work until a library is created"                          | No library yet. Run `npm run createLib -- <Library> <version> Y Current`.                                      |
+| A command hangs or prints a prompt                                               | Arguments were omitted. Re-run with every positional argument.                                                 |
+| `Cannot find package '@eslint-react/eslint-plugin'` or other missing packages    | Dependencies are not installed. Run `npm install` in the project, then retry.                                  |
+| Jest fails with `ReferenceError: Highlight is not defined`                       | `setupTests.ts` is missing the `Highlight` stub that `@pega/cosmos-react-core` needs under jsdom. Add the stub. |
+| `Invalid: data/properties/N must have required property ...` from `validate-schema` | Property N (zero-based) in `config.json` lacks `name`, `label` or `format`.                                  |
+| `Invalid: data/subtype must be equal to one of the allowed values`                | The subtype has the wrong value or casing. Use a value from the table above.                                   |
+| `Property 'PCore' does not exist on type 'Window'` in `demo.stories.tsx`         | Known noise in scaffolded stories; not part of the bundle.                                                     |

package/src/ai/project/.claude/skills/create-dx-component/references/component-patterns.md

@@ -0,0 +1,241 @@
+# Component Implementation Patterns
+
+## Field Component Pattern
+
+Field components bind to a single case property and handle input/display with validation.
+
+```typescript
+import { Input, withConfiguration } from '@pega/cosmos-react-core';
+import type { PConnFieldProps } from '../shared/PConnProps';
+import '../shared/create-nonce';
+import handleEvent from './event-utils';
+import StyledWrapper from './styles';
+
+interface Props extends PConnFieldProps {
+  // Additional props from config.json
+  hasSuggestions?: boolean;
+  variant?: any;
+  formatter?: string;
+}
+
+interface StateProps {
+  value: string;
+  hasSuggestions: boolean;
+}
+
+function AcmeLibMyField(props: Props) {
+  const {
+    getPConnect,
+    value = '',
+    label = '',
+    helperText = '',
+    validatemessage,
+    hideLabel,
+    testId,
+    additionalProps = {},
+    displayMode,
+    placeholder
+  } = props;
+  
+  const pConn = getPConnect();
+  const actions = pConn.getActionsApi();
+  const stateProps = pConn.getStateProps() as StateProps;
+  const propName: string = stateProps.value;
+
+  let { readOnly = false, required = false, disabled = false } = props;
+  [readOnly, required, disabled] = [readOnly, required, disabled].map(
+    (prop) => prop === true || (typeof prop === 'string' && prop === 'true')
+  );
+
+  let status: 'error' | 'success' | 'warning' | 'pending' | undefined;
+  if (validatemessage) {
+    status = 'error';
+  }
+
+  // Display mode (required for all Field components)
+  if (displayMode === 'DISPLAY_ONLY') {
+    return <StyledWrapper>{value}</StyledWrapper>;
+  }
+
+  // Edit mode
+  return (
+    <StyledWrapper>
+      <Input
+        {...additionalProps}
+        label={label}
+        labelHidden={hideLabel}
+        info={validatemessage || helperText}
+        status={status}
+        value={value}
+        placeholder={placeholder}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        testId={testId}
+        onChange={(event: any) => {
+          handleEvent(actions, 'change', propName, event.target.value);
+        }}
+        onBlur={(event: any) => {
+          handleEvent(actions, 'blur', propName, value);
+          pConn.getValidationApi().validate(value);
+        }}
+      />
+    </StyledWrapper>
+  );
+}
+
+export default withConfiguration(AcmeLibMyField);
+```
+
+### event-utils.ts (Field Components)
+
+```typescript
+const handleEvent = (actions: any, eventType: string, propName: string, value: any) => {
+  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;
+```
+
+---
+
+## Template Component Pattern
+
+Templates arrange child components in layouts (forms, details views, pages). `children` holds one element per **region**; fields are one level down. This skeleton is the editable-layout starting point only. For read-only rendering, per-field layout, responsive columns and hidden children read [template-patterns.md](./template-patterns.md).
+
+```typescript
+import { Grid, Flex, FieldGroup, withConfiguration } from '@pega/cosmos-react-core';
+import type { PConnFieldProps } from '../shared/PConnProps';
+import '../shared/create-nonce';
+import StyledWrapper from './styles';
+
+interface Props extends PConnFieldProps {
+  children: any[];
+  NumCols?: string;
+  showLabel?: boolean;
+}
+
+function AcmeLibMyTemplate(props: Props) {
+  const { children = [], NumCols = '1', label, showLabel, getPConnect, readOnly, displayMode } = props;
+  const propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() };
+  const nCols = parseInt(NumCols, 10);
+
+  return (
+    <StyledWrapper>
+      <FieldGroup name={propsToUse.showLabel ? propsToUse.label : ''}>
+        <Grid container={{ cols: `repeat(${nCols}, minmax(0, 1fr))`, gap: 2 }}>
+          {children}
+        </Grid>
+      </FieldGroup>
+    </StyledWrapper>
+  );
+}
+
+export default withConfiguration(AcmeLibMyTemplate);
+```
+
+---
+
+## Widget Component Pattern
+
+Widgets are standalone UI blocks that fetch their own data.
+
+```typescript
+import { useState, useEffect } from 'react';
+import { Table, Card, CardHeader, CardContent, Text, withConfiguration } from '@pega/cosmos-react-core';
+import type { PConnFieldProps } from '../shared/PConnProps';
+import '../shared/create-nonce';
+import StyledWrapper from './styles';
+
+interface Props extends PConnFieldProps {
+  // Widget-specific props
+}
+
+function AcmeLibMyWidget(props: Props) {
+  const { getPConnect, label } = props;
+  const pConn = getPConnect();
+  const [data, setData] = useState<any[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const context = pConn.getContextName();
+
+  useEffect(() => {
+    const caseProp: string = PCore.getConstants().CASE_INFO.CASE_INFO_ID;
+    const caseID = pConn.getValue(caseProp, '');
+    const payload = { dataViewParameters: { CaseInstanceKey: caseID } };
+
+    PCore.getDataApiUtils()
+      .getData('D_DataPageName', payload, context)
+      .then((response: any) => {
+        setIsLoading(false);
+        if (response.data.data !== null) {
+          setData(response.data.data);
+        }
+      })
+      .catch(() => {
+        setData([]);
+        setIsLoading(false);
+      });
+  }, [context]);
+
+  return (
+    <StyledWrapper>
+      <Card>
+        <CardHeader>
+          <Text variant="h2">{label}</Text>
+        </CardHeader>
+        <CardContent>
+          {/* Render data */}
+        </CardContent>
+      </Card>
+    </StyledWrapper>
+  );
+}
+
+export default withConfiguration(AcmeLibMyWidget);
+```
+
+---
+
+## Presentation Component Pattern
+
+Presentation components (`CASEVIEW`, `WSSCASEVIEW`) replace how a whole case view is rendered. They receive everything as props and cannot use PCore or PConnect.
+
+```typescript
+import { withConfiguration } from '@pega/cosmos-react-core';
+import type { CaseViewProps } from '@pega/cosmos-react-work';
+import '../shared/create-nonce';
+import StyledWrapper from './styles';
+
+function AcmeLibMyCaseView(props: CaseViewProps) {
+  const { caseId, heading, caseType, tabs, tabContent } = props;
+  const activeTab = tabContent?.find((tab) => tab.id === tabs.currentTabId);
+
+  return (
+    <StyledWrapper>
+      <header>
+        <span>{caseType}</span>
+        <h1>{typeof heading === 'string' ? heading : heading?.text}</h1>
+        <span>{caseId}</span>
+      </header>
+      {activeTab?.content}
+    </StyledWrapper>
+  );
+}
+
+export default withConfiguration(AcmeLibMyCaseView);
+```
+
+Always start from the scaffolded `index.tsx` (`npm run create -- Presentation CASEVIEW ...`) and read the prop types in `node_modules/@pega/cosmos-react-work/lib/components/CaseView/CaseView.types.d.ts` before using a prop. For `WSSCASEVIEW` the type comes from `@pega/cosmos-react-wss`.