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

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

@@ -0,0 +1,296 @@
+# Config.json Schema Reference
+
+The `config.json` file defines component metadata and configurable properties that appear in the Pega Constellation authoring environment.
+
+## Base Structure
+
+```json
+{
+  "name": "<Org>_<Library>_ComponentName",
+  "label": "Human Readable Label",
+  "description": "Brief description of the component",
+  "organization": "<Org>",
+  "version": "1.0.0",
+  "library": "<Library>",
+  "componentKey": "<Org>_<Library>_ComponentName",
+  "type": "Field|Template|Widget|Presentation",
+  "subtype": "Text|Boolean|FORM|DETAILS|CASE|PAGE|CASEVIEW",
+  "subtypeLabel": "Human readable subtype",
+  "icon": "optional-icon.svg",
+  "properties": [],
+  "defaultConfig": {}
+}
+```
+
+## Type-Specific Configurations
+
+### Field Component
+```json
+{
+  "type": "Field",
+  "subtype": "Text",
+  "subtypeLabel": "Text",
+  "properties": [
+    { "name": "label", "label": "Field label", "format": "TEXT" },
+    { "name": "hideLabel", "label": "Hide Label", "format": "BOOLEAN" },
+    { "name": "readOnly", "label": "Edit mode", "format": "READONLY" },
+    {
+      "label": "Input settings",
+      "format": "GROUP",
+      "visibility": "(!readOnly = true)",
+      "properties": [
+        { "name": "helperText", "label": "Helper text", "format": "TEXT" },
+        { "name": "placeholder", "label": "Placeholder", "format": "TEXT" }
+      ]
+    },
+    {
+      "label": "Conditions",
+      "format": "GROUP",
+      "properties": [
+        { "name": "required", "label": "Required", "format": "REQUIRED", "visibility": "(!readOnly = true)" },
+        { "name": "disabled", "label": "Disabled", "format": "DISABLED" },
+        { "name": "visibility", "label": "Visibility", "format": "VISIBILITY" }
+      ]
+    },
+    {
+      "label": "Advanced",
+      "format": "GROUP",
+      "collapsible": true,
+      "properties": [
+        { "name": "testId", "label": "Test ID", "format": "TEXT", "includeAnnotations": false }
+      ]
+    }
+  ]
+}
+```
+
+### Template Component
+```json
+{
+  "type": "Template",
+  "subtype": "FORM",
+  "subtypeLabel": "FORM",
+  "properties": [
+    {
+      "format": "SELECT",
+      "name": "NumCols",
+      "label": "Number of columns",
+      "defaultValue": "1",
+      "source": [
+        { "key": "1", "value": "One" },
+        { "key": "2", "value": "Two" },
+        { "key": "3", "value": "Three" }
+      ]
+    },
+    { "format": "INSTRUCTIONS" },
+    {
+      "name": "Fields",
+      "label": "Fields",
+      "format": "CONTENTPICKER",
+      "allowCreatingGroup": true
+    }
+  ]
+}
+```
+
+### Widget Component
+```json
+{
+  "type": "Widget",
+  "subtype": "CASE",
+  "subtypeLabel": "CASE",
+  "properties": [
+    { "name": "label", "label": "Label value", "format": "TEXT" }
+  ],
+  "defaultConfig": {
+    "label": "@L My Widget Label"
+  }
+}
+```
+
+## Property Format Reference
+
+| Format | Description | Additional Fields |
+|--------|-------------|-------------------|
+| `TEXT` | Free text input | — |
+| `SELECT` | Dropdown | `source: [{key, value}]`, `defaultValue` |
+| `BOOLEAN` | Toggle | `defaultValue: true/false` |
+| `NUMBER` | Numeric | — |
+| `READONLY` | Edit mode toggle | — |
+| `REQUIRED` | Required toggle | — |
+| `DISABLED` | Disabled toggle | — |
+| `VISIBILITY` | Condition expression | — |
+| `CONTENTPICKER` | Add fields/views | `addTypeList`, `allowCreatingGroup`, `saveToConfig` |
+| `DATASOURCE` | Data page binding | — |
+| `GROUP` | Nested property group | `properties: [...]` |
+| `INSTRUCTIONS` | Help text | — |
+| `VALUEINPUT` | Value with rule type | `ruleType` |
+
+## Visibility Expressions
+
+Properties can be conditionally shown. Forms seen in shipped configs:
+
+- `"visibility": "(!readOnly = true)"` — a bare sibling property name with a single `=`, in parentheses
+- `"visibility": "$this.columnWidth == 'custom'"` — `$this.` prefix with `==` (also `!=`, `!==`)
+- `"visibility": "!($this.readOnly == true)"` — negation
+- `"visibility": "hideLabel == false || hideLabel IS_NULL"` — combine with `&&` and `||`
+- `"visibility": "$this.mode CONTAINS 'single'"` — `CONTAINS`, `STARTS_WITH`, `IS_NULL`, `IS_NOT_NULL`, `IS_IN_LIST`
+- `"visibility": "@PLATFORMNAME != 'launchpad'"` — platform-specific; the one `@` context variable proven for custom components
+
+Prefer `$this.<prop>` or the parenthesized bare name over a bare `$prop`; no shipped config uses `$prop`. Other `@` variables (`@VIEWTYPE`, `@VIEWTEMPLATESUBTYPE`, `@RULEVIEWTYPE`, `@ISHYBRIDAPP`, and so on) appear in Pega's own configs, but there is no evidence they are available to custom components. Do not invent a variable because its name sounds right. Compare to the correct type: do not compare a boolean to the string `'true'` unless a shipped example does.
+
+## DefaultConfig
+
+Use `defaultConfig` to set initial values when the component is first added:
+```json
+{
+  "defaultConfig": {
+    "label": "@L Default Label",
+    "NumCols": "2"
+  }
+}
+```
+
+The `@L` prefix marks the value as localizable.
+
+## What `validate-schema` checks
+
+`npm run validate-schema -- <Org>_<Library>_<Name>` (also the first step of `buildComponent`) checks the structure of the file, **not** whether the platform understands a `format`. The rules, from the CLI validator:
+
+- Required top-level keys: `componentKey`, `name`, `description`, `type`, `subtype`, `properties`. `label`, `icon` and `organization` are not required by the schema (library mode still enforces `organization` and `library`; see Key and property rules). Extra top-level keys are allowed.
+- `name` and `componentKey` match `^[A-Za-z0-9]+_[A-Za-z0-9]+_[A-Za-z0-9]+$`.
+- `description` is not blank.
+- `type` is one of `Field`, `Template`, `Widget`, `Presentation`. `subtype` is one of the values in [Valid `subtype` values](#valid-subtype-values), with exact casing (for example `TimeOfDay`). The Presentation subtypes (`CASEVIEW`, `WSSCASEVIEW`) are valid only on `Presentation`, and `Presentation` accepts only those.
+- `properties` is an array with **unique** entries. Each entry must match one of three shapes:
+  1. `name`, `label` and `format` (the normal control).
+  2. A `CASCADE`: `format`, plus a `source` object (`name`, `label`, `format`) and `cascadeElements` where each element has `key`, `name`, `label` and `format`. Only `format` is required.
+  3. A `GROUP`: `label` and `format`, with a nested `properties` array whose entries are a normal control, a `LABEL` (`variant`, `label`, `format`) or an `INLINE` (`format` and `elements`, each element with `key`, `format` and `label`). `GROUP` has no `name`.
+- A bare `{ "format": "INSTRUCTIONS" }` passes (through the `CASCADE` shape, which only requires `format`).
+
+**`format` is only checked to be a string.** A misspelled or unsupported format passes `validate-schema` and `buildComponent` and then fails (or silently does nothing) in App Studio. Use only formats from the tables below, and check any other against a scaffold of the same type.
+
+Typical errors: `Invalid: data/properties/N must have required property 'label'` (property N, zero-based, is incomplete), `data/properties must NOT have duplicate items` (two identical entries), and `Invalid: data/subtype must be equal to one of the allowed values`.
+
+## More formats and members
+
+**Scaffold-proven.** The CLI scaffolds use exactly these 17 formats, so they are safe for custom components: `GROUP`, `TEXT`, `SELECT`, `NUMBER`, `BOOLEAN`, `VISIBILITY`, `REQUIRED`, `DISABLED`, `READONLY`, `VALUEINPUT`, `LABEL`, `CONTENTPICKER`, `CASCADE`, `PROPERTY`, `INLINE`, `DATASOURCE`, `INSTRUCTIONS`.
+
+| Format | Notes and members |
+| --- | --- |
+| `TEXT` | `helperText`, `helperTextVisibility` (same grammar as `visibility`), `placeholder`, `ignorePattern` (characters stripped from input), `includeAnnotations` (default true), `allowsDynamicText`, `multiline` |
+| `NUMBER` | `min`, `max` (min defaults to 0), `showDecimal`, `numberOfDecimals`. Store a number, not a string |
+| `BOOLEAN` | `defaultValue`; give it a positive label such as `Show profile` and set the default explicitly when absent and false differ |
+| `SELECT` | `source: [{ key, value }]`, `defaultValue`, `placeholder`, `helperText`, `localize`. Persist the stable `key`; `value` is the display text |
+| `GROUP` | Nested `properties`, `collapsible`, `defaultCollapsed`, `visibility`. A group is not a runtime property and is never serialized |
+| `CONTENTPICKER` | Templates only. `addTypeList` (values seen: `Fields`, `Views`, `Widgets`, `Insights`, `Associations`), `allowCreatingGroup`, `saveToConfig`, `source`, `itemTypes` |
+| `PROPERTY` | Property picker. `ofContextClass`, `filter` (for example `"$this.typeKey == 'Pega-Fields-Scalar-Integer'"`), `useAnnotation`, `inheritedProp` |
+| `CASCADE` | One property controls which dependent control is shown. `source` is a full property object, `cascadeElements` each carry a `match` value, `clearElementsOnSwitch` clears hidden values on a switch |
+| `LABEL`, `INLINE` | Layout in the property panel. `LABEL` takes `variant` (`primary`, `secondary`, `h1` to `h6`); `INLINE` has an `elements` array |
+| `VALUEINPUT` | Value with a rule type (`ruleType`, for example `"Paragraph"`), `allowsDynamicText` |
+| `DATASOURCE` | Data page binding; has a nested `properties` array of the fields to read from the source |
+| `VISIBILITY`, `REQUIRED`, `DISABLED`, `READONLY` | Platform-aware condition editors, not plain booleans. `REQUIRED` and `DISABLED` also take `inheritedProp` |
+
+**Seen in Pega's own components, support for custom components unconfirmed:** `FIELDLABELINPUT`, `EXPRESSION`, `DEFAULTVALUE`, `CASELINK`, `VIEWPICKER`, `DATAPAGE`, `PARAMETERS`, `GROUPBY`, `ACTIONPICKER`, `COLUMNFILTER`, `COLUMNSORT`, `COLUMNFORMATTER`, `FILLCOLUMNWIDTH`, `PRESETPICKER`, `CONTENTPICKERSOURCE`, `RENDERMODE`, `EDITMODE`, `MULTIRECORDDISPLAYAS`, `AUTOGENERATED`. Because `validate-schema` accepts any string, a format from this list will pass validation even if App Studio ignores it. Do not use one unless the user supplies a working example, and say so when you do.
+
+If you need a format that is not listed, copy a similar property from a scaffolded component of the same type (`node_modules/@pega/custom-dx-components/src/tasks/create/templates/Constellation/<Type>/<Subtype>/config.json.mustache`) rather than inventing one.
+
+## Standard Field property layout
+
+Pega's own Fields follow one order, and so do the scaffolds. Keep it so the property panel feels familiar:
+
+1. `label`, `hideLabel`, `readOnly` at the top level.
+2. A `GROUP` "Input settings" (edit-only settings such as `placeholder`, `helperText`), gated by `"visibility": "(!readOnly = true)"`.
+3. A `GROUP` "Read-only settings" for display formatting, when there is any.
+4. A `GROUP` "Conditions" with `REQUIRED` (edit-only), `DISABLED` and `VISIBILITY`.
+5. A collapsible `GROUP` "Advanced" with a `testId` property:
+
+```json
+{
+  "label": "Advanced",
+  "format": "GROUP",
+  "collapsible": true,
+  "properties": [
+    {
+      "name": "testId",
+      "label": "Test ID",
+      "format": "TEXT",
+      "ignorePattern": "[^-_\\p{N}\\p{L}]",
+      "includeAnnotations": false
+    }
+  ]
+}
+```
+
+Property `name` is camelCase for Fields and Widgets. Template region and layout names are PascalCase or a single letter (`NumCols`, `Fields`, `A`, `B`); do not rename them in a copied scaffold. `label` text is sentence case and is never prefixed with `@L`; only default values are localized that way. Keep `helperText` to one short sentence about a consequence or constraint; use `additionalInfo: { heading?, content }` for anything longer.
+
+## Authoring design rules
+
+- **Persist a stable key, not a label.** A `SELECT` stores its `key`; the `value` can be translated. Changing a `key` breaks every saved view.
+- **Hidden does not mean deleted.** When a visibility condition or `CASCADE` hides a property, its old value stays in the saved metadata. Decide for each conditional property whether the component ignores, clears or still honors it, and make `index.tsx` safe against a stale value. Use `clearElementsOnSwitch` when a stale value would change meaning.
+- **Defaults apply only when the key is absent.** They do not repair a malformed saved value. The precedence is saved value, then `defaultConfig` / `defaultValue`, then the fallback in the component. Treat absent, `null`, `''`, `0` and `false` as different inputs and say which the component accepts.
+- **Keep authoring settings separate from runtime state.** Focus, hover, open menus, request status and filter text never belong in `config.json`. Secrets, endpoints and data page names that vary per environment do not either.
+- **Fewer properties is better.** Every property adds persisted surface, test cases and migration cost. Start with the smallest set that makes the component usable.
+- **Do not expose two controls for one runtime key** unless their visibility conditions are mutually exclusive.
+
+### Property ledger
+
+Keep this table in the plan for any component with more than a couple of properties. A key is unfinished until every column is known; mismatches (`readOnly` in JSON but `readonly` in code, a string default for a number, a picker that persists objects while the code expects strings) are the usual bugs.
+
+| Config key | Format | Default | Prop in `index.tsx` | Hidden or legacy behavior | Test |
+| --- | --- | --- | --- | --- | --- |
+| `maxLength` | `NUMBER` | none | `maxLength?: number` | ignored when not a positive number | boundary story and test |
+
+### Safe and risky changes to an existing component
+
+Adding an optional property is low risk when it has a backward-compatible default, existing metadata renders identically when the key is absent, and it does not hide or reinterpret an existing control. Test both the absent key and an explicit value.
+
+These need an explicit compatibility decision from the user, because saved views already use the old shape: renaming `name` or a property key or region name, changing the type of a saved value, changing a `SELECT` `key`, changing a `CONTENTPICKER` from scalars to objects, removing a property or region, and changing `defaultConfig` so existing components behave differently. Prefer adding the new shape and keeping the old one.
+
+## `defaultConfig` bindings
+
+Besides literals, scaffolds use these bindings in `defaultConfig`:
+
+| Binding                                     | Meaning                                                       |
+| ------------------------------------------- | ------------------------------------------------------------- |
+| `"@P .pyLabel"`                             | Value of a property on the current page                       |
+| `"@L $this.label"`, `"@L Select..."`        | Localized text (the field's own label, or a literal)          |
+| `"@DATASOURCE D_pyAnnouncements.pxResults"` | A data page and the result list to bind to                    |
+| `"@ASSOCIATED .$this.name"`                 | The associated (list-of-values) source for the bound property |
+| `"@FL .$this.name"`                         | The bound property's field label (the most common default for a Field `caption`) |
+
+Scaffolded fields also carry layout flags in `defaultConfig` (for example `detailFVLItem`, `isFormWidth`). Leave them as generated.
+
+## Keep `config.json` and `index.tsx` in sync
+
+- Add a property: add the entry to `properties`, add the prop (with its type) to the props interface in `index.tsx`, and use it in the component. Give it a safe default in the destructuring (`const { max = 100 } = props;`) because a designer may leave it empty.
+- Remove a property: remove it from all three places.
+- Rename a property: it is a breaking change for any view that already configures it. Prefer adding a new property and keeping the old one until the user confirms.
+- Boolean and numeric properties can reach the component as strings. Normalize them before use, as the scaffolded fields do for `readOnly`, `required` and `disabled` (and `parseInt` for numeric settings such as `decimalPrecision`).
+- After editing, run `npm run validate-schema -- <Org>_<Library>_<Name>`.
+
+## Key and property rules
+
+- `name` must match the folder name exactly, and `componentKey` must equal `name`.
+- `library` must match `component.library` in [tasks.config.json](../../../../tasks.config.json), and `organization` must match the organization there (library mode enforces both).
+- `icon` is optional and names an SVG in the component folder.
+- `SELECT` requires a `source` array of `{ "key", "value" }` pairs. `GROUP` carries a nested `properties` array and has no `name`. `INSTRUCTIONS` renders help text and has no `name`. `CONTENTPICKER` is for Templates: it lets App Studio authors add child fields and views.
+- Every `name` must match a prop consumed in `index.tsx`. Do not declare properties the component ignores.
+
+## Valid `subtype` values
+
+
+Use these exact values (the CLI `create` argument and `config.json` `subtype`). A wrong value or casing fails `validate-schema` with `data/subtype must be equal to one of the allowed values`.
+
+| type           | subtype                                                                                                                                                                                       |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`     | `FORM`, `FORM-region`, `DETAILS`, `DETAILS-region`, `PAGE`                                                                                                                                    |
+| `Widget`       | `CASE`, `PAGE`, or the array `["PAGE", "CASE"]` (shown in the picker as "PAGE & CASE")                                                                                                         |
+| `Presentation` | `CASEVIEW`, `WSSCASEVIEW`                                                                                                                                                                     |
+
+[component-manifest.json](../../generate-component-set/component-manifest.json) maps each friendly subtype name to its `cliSubtype`.
+
+## Grouping convention
+
+
+Put `label`, `hideLabel`, and `readOnly` at the top level. Group the rest by concern with `GROUP`, and gate edit-only settings behind `"visibility": "(!readOnly = true)"`.

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

@@ -0,0 +1,137 @@
+# Cosmos React Core - Available Components
+
+Every name below was checked against the barrel in `node_modules/@pega/cosmos-react-core/lib/index.d.ts`. **Verify any name that is not on this list before you import it** — several plausible-sounding components (`Divider`, `Badge`, `DataGrid`, `IconButton`, `Tab`) do **not** exist.
+
+## Layout Components
+- `Grid` — CSS Grid layout container
+- `Flex` — Flexbox layout container
+- `Card` — Card container with shadow/border
+- `CardHeader` — Card header section
+- `CardContent` — Card content section
+- `FieldGroup` — Group of fields with optional label
+- `FormField` — Label + control + info + actions wrapper
+
+## Input Components
+- `Input` — Text input field
+- `TextArea` — Multi-line text input
+- `Checkbox` — Single checkbox
+- `CheckboxGroup` — Group of checkboxes
+- `RadioButtonGroup` — Radio button selection
+- `Select` — Dropdown select
+- `DateInput` — Date picker input
+- `TimeInput` — Time picker input
+- `NumberInput` — Numeric input
+- `CurrencyInput` — Currency input with formatting
+- `PhoneInput` — Phone number input
+- `SearchInput` — Search input with icon
+
+## Display Components
+- `Text` — Typography component (variants: h1-h6, body, caption)
+- `FieldValueList` — Label-value pair display (variants: inline, stacked)
+- `BooleanDisplay` — True/false display
+- `DateTimeDisplay` — Formatted date/time
+- `CurrencyDisplay` — Formatted currency
+- `PhoneDisplay` — Formatted phone number
+- `EmailDisplay` — Email with link
+- `URLDisplay` — URL with link
+- `Icon` — SVG icon display
+- `Avatar` — User avatar
+- `Progress` — Progress bar/indicator
+- `EmptyState` — Empty view placeholder
+
+## Badges (all from `./components/Badges`)
+- `Status` — Status badge/indicator
+- `Tag` — Label chip
+- `Count` — Numeric badge
+- `Alert` — Alert badge
+- `Selectable`, `Keyboard`
+
+## Data Components
+- `Table` — Data table with columns, sorting, pagination
+
+## Feedback Components
+- `Banner` — Banner notification
+- `Toaster` — Toast notifications
+- `Modal` — Modal dialog (see gotchas)
+- `FormDialog` / `InfoDialog` — Anchored dialogs
+
+## Navigation Components
+- `Link` — Hyperlink
+- `Button` — Action button
+- `Tabs` — Tabbed navigation (**not** `Tab`)
+
+## HOCs & Utilities
+- `withConfiguration` — **Required wrapper** for all DX components
+- `ShortcutManager` — Keyboard shortcut handling
+- `PopoverManager` — Popover positioning
+- `ModalManager` — Modal dialog management
+- `useTheme` — Cosmos theme access (see gotchas)
+- `useModalManager` — Imperative modal creation
+
+## Additional components used by Pega's own widgets and templates
+
+These are exported by `@pega/cosmos-react-core` (or `@pega/cosmos-react-work` where noted) in recent builds. Check the export and prop names in the installed `.d.ts` before use; several came from a newer Cosmos than a customer project may have.
+
+| Need | Component or helper | Notes |
+| --- | --- | --- |
+| Summary list with loading, count, per-item actions and focus after delete | `SummaryList`, `ViewAll` | `loading`, `count` (pass `undefined` while loading), `noItemsText`, `onViewAll`, item `contextualLabel`, and `deletedItemId` + `onDeleteFocusComplete` + `fallbackFocusRef` |
+| Error with retry | `ErrorState` | props are `message` and `onRetry` only; its retry button reads "Try again" |
+| Destructive confirm | `Modal`, `DangerButton`, `useModalManager`, `useModalContext` | see [widget-patterns.md](./widget-patterns.md) |
+| Focus an error summary | `Banner` with a `handle` | `handle.current.focus()`; `messages` must be an array |
+| Progress placement | `Progress` | `placement` is `'block'`, `'local'` (needs a positioned parent) or `'inline'`; `variant` is `'ring'`, `'bar'` or `'ellipsis'` |
+| Grouped fields | `FieldGroup`, `FieldGroupList` | `fieldset`/`legend`; `collapsed`, `status='error'`, `headingTag` |
+| Tabs | `Tabs`, `TabPanel` | ARIA and arrow keys are built in; do not reimplement |
+| Page layouts | `OneColumnPage`, `TwoColumnPage`, `ThreeColumnPage`, `NarrowWidePage`, `WideNarrowPage`, `TabbedPage` | slots `a`, `b`, `c`; they own scrolling and heading focus |
+| Read-only label/value lists | `FieldValueList`; `Details`, `DetailsList`, `DetailsContext` from `@pega/cosmos-react-work` | `Details` handles column fitting and label alignment |
+| Display formatting | `DateTimeDisplay`, `CurrencyDisplay`, `NumberDisplay`, `EmailDisplay`, `PhoneDisplay`, `BooleanDisplay`, `ParagraphDisplay`, `URLDisplay`, `NoValue` | prefer to hand formatting |
+| Utilities | `useBreakpoint`, `useTheme`, `useConfiguration`, `createUID`, `debounce`, `createStringMatcher`, `formatNumber`, `useElement`, `LocaleOverride`, `getPhoneNumberParts` | create a `debounce` once (`useMemo`), never in the render body |
+| Safe links | `disallowedURI` | present in some builds; keep your own protocol allow-list as well |
+
+## Verified Gotchas
+
+Each of these was confirmed by reading the installed package. They are the opposite of what the prop names suggest.
+
+| Component | Trap |
+| --- | --- |
+| `Banner` | `messages` must be an **array**. Passing a string throws `messages.flatMap is not a function`. |
+| `EmptyState` | The prop is `message`, **not** `title`. A `title` prop is silently ignored. |
+| `Tag` | Requires `children`. There is **no** `label` prop. |
+| `Input` | Does **not** render a character counter. `maxLength` only sets the native attribute. Only `TextArea` has `displayCharCount`. |
+| `Input` | Renders its own `FormField` when `label` is passed. Composing it inside your own `FormField` while also passing `label` nests two of them. |
+| `FormField` | `onClear` is gated behind `isRadioCheck` — it renders **only** for radio/checkbox groups. For a text input, use the `actions` array. |
+| `FormField` / `Input` | Pass the **same explicit `id`** to both, or the label's `htmlFor` will point at a different generated id. |
+| `Modal` | Needs a `ModalManager` ancestor. Without one, `useModalManager().create()` is a silent no-op and `dismiss` does nothing. |
+| — | There is **no floating-label** API anywhere in Cosmos. Build it in `styles.ts`. |
+
+### styled-components theme does not cross the boundary
+
+`@pega/cosmos-react-core` bundles its **own nested copy** of `styled-components`. Its `ThemeProvider` therefore does not populate the `ThemeContext` used by a component's own `styles.ts`, and `theme.base` is `undefined` there.
+
+Read the theme in `index.tsx` and pass the values down as props:
+
+```typescript
+import { useTheme } from '@pega/cosmos-react-core';
+
+const palette = useTheme().base.palette;
+// palette['primary-background'] | palette['foreground-color'] | palette.urgent | palette.success
+<StyledWrapper $error={palette.urgent} />
+```
+
+## Import Pattern
+```typescript
+import {
+  Grid,
+  Flex,
+  Card,
+  CardContent,
+  Text,
+  Input,
+  Table,
+  withConfiguration
+} from '@pega/cosmos-react-core';
+```
+
+## Additional Cosmos Libraries
+- `@pega/cosmos-react-work` — Work-related components (assignments, cases)
+- `@pega/cosmos-react-wss` — Workspace components
+- `@pega/cosmos-react-condition-builder` — Condition/filter builder

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

@@ -0,0 +1,155 @@
+# Field Behavior
+
+How production Constellation Fields commit values, handle empty and zero, and report status. This is the shared contract behind every Field subtype skill; the subtype skills only add what differs. Props and display modes are in [props-contract.md](./props-contract.md), states in [state-matrix.md](./state-matrix.md).
+
+The behaviors below were observed in Pega's own Field components. Cosmos callback shapes can differ between Cosmos versions, so check the control's `.d.ts` in the installed `@pega/cosmos-react-core` before relying on a shape (see Verified Gotchas in [cosmos-components.md](./cosmos-components.md)).
+
+## Commit protocol
+
+`handleEvent(actions, type, propName, value, options?)` from `shared/event-utils` maps to the PConnect actions API:
+
+| `type` | Calls |
+| --- | --- |
+| `'change'` | `updateFieldValue(prop, value, options)` |
+| `'blur'` | `triggerFieldChange(prop, value)` |
+| `'changeNblur'` | both, in that order |
+
+Which event commits depends on the control. Follow the contract for the subtype instead of committing on every keystroke:
+
+| Family | While typing | On blur |
+| --- | --- | --- |
+| Text, TextArea, Email, URL | keep a local draft, clear the field error, `pConn.updateDirtyCheckChangeList(propName, draft)` | commit with `changeNblur` only if the value differs from the stored one |
+| Integer, Decimal, Percentage, Currency | validate the draft, keep it local, clear the field error | convert to a number (or `''`), compare, `changeNblur` if different |
+| Date, DateTime, Time | pickers commit when a complete valid date is entered (see Dates) | same helper |
+| Dropdown, RadioButtons, Checkbox | `changeNblur` straight from the change event | `validate(value)` (RadioButtons only when there is no value) |
+| Stepper or slider variants | `changeNblur` on change, because they may never fire blur | none |
+
+Rules that apply to every family:
+
+- **Read the value from the control's blur callback argument, not from React state.** State may not have updated yet; a decimal point inserted into `805` to make `8.05` must still commit.
+- **Do nothing when the value is unchanged.** If the draft equals the stored value, do not commit. If both are empty, call `getValidationApi().validate('')` only, so a required field still reports its error.
+- **Zero is a value.** Never write `if (!value)` for a number. Typing `0` over an empty field commits `0`; clearing a stored `0` commits `''`.
+- **Compare as strings (or the parsed form), never with epsilon.** Compare `value.toString()` with the parsed text, so `1.600` redisplays as `1.6` after commit.
+- **Clear means `''`.** Production numeric fields send `''` (not `null`, not `0`) when the user clears the input. See [Empty and null](#empty-and-null).
+- **Guard blur with `!readOnly`** so a read-only control cannot commit.
+- **Wire error clearing and the dirty list.** On change call `pConn.clearErrorMessages({ property: propName })` (documented), so a stale error disappears as soon as the user edits. Pega's own fields that keep a local draft also call `pConn.updateDirtyCheckChangeList(propName, value)`. That method is in the PConnect typedefs but **not in the API catalog**: confirm it in `node_modules/@pega/pcore-pconnect-typedefs`, and tell the user you are using it, before adding it.
+- **Local draft state needs a sync effect.** Keep `useState(String(value))` for the control and an effect on `[value]` that overwrites it when the store changes (a reset, a cascade, a suggestion accepted).
+
+## Empty and null
+
+`value` can be `null` for a property that was never set. A destructure default (`value = ''`) does not cover `null`; use `const value = valueProp ?? ''`.
+
+Test these inputs for every numeric and text field: `null`, `''`, `0`, a stored value, and a typed value over `null`.
+
+| Subtype | `null` mounts as | Notes |
+| --- | --- | --- |
+| Text, Integer, Decimal, Currency, Percentage | empty input | display mode shows `NoValue` (Text shows `0` for a real zero) |
+| Boolean checkbox | unchecked | writes `false` with `{ skipDirtyValidation: true }` so the form is not dirtied; no `triggerFieldChange` |
+| Boolean as two radios | neither selected | skip the null-to-false write so "unset" stays distinct from "false" |
+| Picklist | first option, or `''` when a placeholder exists | see [picklist](../../picklist/SKILL.md) |
+
+## Message precedence
+
+- `info` shown under the control is `validatemessage` if non-empty, else the field warning content, else `helperText`. A validation message **replaces** the helper text.
+- `status` passed to the Cosmos control: `'error'` when `validatemessage` is non-empty, `'pending'` while a suggestion is available, `'warning'` for a field warning, otherwise `undefined`. Never pass the internal value `'suggestion-accepted'` to a Cosmos control; map it to `undefined`.
+- **Field warning.** `showFieldMessage` plus `messageConfig: { visibility, content }` shows a non-blocking warning when `showFieldMessage && messageConfig.visibility && !readOnly`. It is suppressed in read-only mode and when the condition is false.
+- `hideLabel` hides the label (`labelHidden`) but helper text still renders.
+- `fieldMetadata` may carry `maxLength`, `additionalInformation` (render as the control's `additionalInfo={{ content }}`) and `inputFormat.pattern` (a mask). `pConn.getFieldMetadata(prop)` returns it; the scaffolds already receive it as a prop. The method is typed in the PConnect typedefs but is not in the API catalog, so prefer the prop, and confirm the method in the typedefs before calling it.
+
+## Boolean-like props arrive as strings
+
+`readOnly`, `required` and `disabled` can arrive as `true`, `'true'` or anything else. Normalize each with `p === true || p === 'true'`. Numeric config such as `decimalPrecision` or `pickerInterval` arrives as a string too; `parseInt` it and fall back deliberately when it is `NaN`.
+
+## `additionalProps`
+
+Spread `{...additionalProps}` **first** on the Cosmos control so explicit props win. `autoFocus` and similar platform props arrive this way. Give the control `testId={testId ?? label}` so tests and test automation have a stable hook.
+
+## Suggestions (AI-assisted values)
+
+When the platform proposes a value, `pConn.acceptSuggestion()` and `pConn.ignoreSuggestion()` (both in the catalog) accept or reject it. Pass `suggestion={{ onAccept, onReject }}` to the Cosmos control, and keep a local `status` that becomes `'suggestion-accepted'` on accept and is cleared on reject, on user edit and after the blur commit. For a Checkbox or radio, call `onAccept` when the click changes the suggested value, otherwise `onReject`. Show the pending status only when the suggested value is among the options.
+
+## Display only
+
+`DISPLAY_ONLY` returns early, after all hooks, with no label or input. An empty value renders `NoValue`. Numeric displays pass `undefined` (not `''`) to `NumberDisplay` or `CurrencyDisplay`. The Cosmos `*Display` components (`DateTimeDisplay`, `CurrencyDisplay`, `NumberDisplay`, `EmailDisplay`, `PhoneDisplay`, `BooleanDisplay`, `ParagraphDisplay`, `URLDisplay`) format values for you; prefer them to formatting by hand. The optional `formatter` prop maps to display variants (for example `Currency`, `Decimal`, `Percentage`, `DateTime-Long`); read it from `pConn.getConfigProps()` at render time.
+
+## Dates, times and time zones
+
+- **Date** values are `YYYY-MM-DD` strings. Never run them through a time zone: parsing `2024-03-01` as local midnight can shift the day. Take the year with `value.slice(0, 4)` and format date-only values with `timeZone: 'UTC'`.
+- **DateTime** values are UTC instants (`YYYY-MM-DDTHH:mm:ss.000Z`). Convert to the operator's zone for the input and back to UTC on commit. The zone comes from `PCore.getEnvironmentInfo().getTimeZone()`; when that is empty and the feature flag `pyEnableDateTimeSystemTimezoneFallback` is on in `getEnvironmentInfo().getFeatureMap()`, fall back to `PCore.getLocaleUtils().getTimeZoneInUse()`.
+- **Time** values are `HH:mm:ss` and commit on blur.
+- **Year range.** Defaults are 100 years back and 20 years forward from today, widened to include the year of the stored value. `min` is `${year}-01-01` and `max` is `${year}-12-31`.
+- **Invalid and incomplete input.** Cosmos date inputs report an error state alongside the value. While the state is invalid or incomplete, keep the draft and call `validate(...)`; do not call `triggerFieldChange`, and do not clear what the user typed. Only a complete valid date is committed.
+- **DateTime options.** `pickerInterval` accepts only 5, 10, 15, 20, 30 or 60 (fall back to 30). `clockFormat` accepts 12 or 24 (fall back to the locale default).
+- Use `LocaleOverride` from Cosmos for a calendar override, and read the locale from `PCore.getEnvironmentInfo().getLocale()`.
+
+## Numbers
+
+- Integer: accept `''`, `'-'`, or text where `Number(s).toString() === s`. That rejects `1.0`, `01` and `1e3` while typing. `showGroupSeparators` defaults to true.
+- Decimal: `numberOfDecimals` is `parseInt(decimalPrecision)`. `NaN` from `''` means unlimited, any other `NaN` means 2. Intermediate drafts such as `-`, `-0`, `-0.` and `-0.0` must survive typing, which is why a draft is validated by its trimmed form rather than by `Number()`. Cosmos `NumberInput` already caps the length.
+- Currency: use the authored `currencyISOCode` prop. Fall back to `PCore.getFieldDefaultUtils().fieldDefaults.Currency.currencyISOCode`, then `'USD'`. Check that a code is valid with `new Intl.NumberFormat('en', { style: 'currency', currency: code })` in a try/catch.
+- Percentage: a platform default (`PCore.getFieldDefaultUtils().fieldDefaults.Percentage.storePercentageAsDecimal`) decides whether `0.25` or `25` is stored. When it is on, display is `value * 100` and commit is `value / 100` rounded to `precision + 2` decimals. Watch the precision fallback: a stored `0.123456` with an empty precision displays as `12.35`.
+
+## Pickers and radios
+
+- Compare option keys as strings: `` `${value}` === `${item.key}` ``. Never key a radio by array index; use the key, and name the group `pageReference.propName` so groups on different pages do not collide.
+- A placeholder is an option with value `''`. With no placeholder and an empty value, production selects the first option and commits it; if the stored value is not among the options it resets to the first option (or `''` with a placeholder). Decide on purpose whether your picker does this, and test it.
+- Dependent options: register through the cascade APIs and cancel stale option requests with an `AbortController` before each search.
+- A single-select combo box keeps the typed filter text separate from the selected item, and clearing the text deselects.
+- A picker that also writes other properties from the selected row calls `updateFieldValue(prop, v)` then `triggerFieldChange(prop, v, true)` for each extra property; the third argument skips validation.
+- Radio deselect is an opt-in (`allowClear`), not the default.
+
+## URL, email and phone
+
+- A display link built by Cosmos `URLDisplay` is not a security boundary. In the Cosmos build checked here, `Link` only drops hrefs that match `javascript:`; `data:`, `vbscript:` and `file:` pass through. Validate scheme yourself (allow `http:`, `https:` and `mailto:` as needed) and test `disallowedURI` from Cosmos where it exists. Open external links with `rel='noopener noreferrer'`.
+- Phone: `PhoneInput` emits country code plus number. A value holding only a country code is junk: on mount write `''` and remember the code locally, and make `required` reject it. Use `getPhoneNumberParts` from Cosmos to split a value.
+- Email and URL commit the raw string like Text. Trimming or lowercasing is your design choice, not platform behavior; say so in the contract.
+
+## Handler shapes
+
+Reference examples for the rules above. Adapt them; do not paste them over the scaffold.
+
+A numeric blur handler (Integer, Decimal, Currency, Percentage):
+
+```typescript
+const onBlur = (event) => {
+  const entered = event.target.value; // read from the event, not from state
+  const next = entered !== '' ? Number(entered) : '';
+  if (String(valueProp ?? '') !== String(next)) {
+    handleEvent(actions, 'changeNblur', propName, next);
+  } else {
+    pConn.getValidationApi().validate(entered); // unchanged or still empty: validate only
+  }
+};
+```
+
+A date callback (Cosmos `DateInput`; verify the shape in the installed `.d.ts`):
+
+```typescript
+const { valueAsISOString, state } = callbackValue;
+const date = valueAsISOString ? valueAsISOString.split('T')[0] : '';
+// state is 'invalid' or 'incomplete' while the user is mid-entry: keep the draft and validate; commit only a complete date
+```
+
+A URL allow-list:
+
+```typescript
+const isSafe = (raw: string) => {
+  try {
+    return ['http:', 'https:'].includes(new URL(raw).protocol);
+  } catch {
+    return false;
+  }
+};
+```
+
+An email normalizer (only if the user agrees to normalize stored data):
+
+```typescript
+const normalized = (value ?? '').trim().toLowerCase();
+handleEvent(actions, 'blur', propName, normalized);
+pConn.getValidationApi().validate(normalized);
+```
+
+## Verification checklist
+
+For every Field, the matching story and test should cover: label, required, disabled, read-only, display only, helper text, validation message replacing helper text, zero, `null`, empty, typing over `null`, unchanged blur (no commit), empty blur (validate only), the commit arguments, and a long value. Details in [test-pattern.md](./test-pattern.md).