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

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

@@ -0,0 +1,90 @@
+# Field essentials
+
+Read this instead of the deep references. Open one only for the cases listed at the end.
+
+## Before you code
+
+- States to cover (mark one not applicable with a reason): empty (`''`, `undefined`, `null`), populated, editing, invalid, required, disabled, read-only, display only, long or malformed value, narrow width, unchanged or empty blur. Add suggestion, field warning and `status` rows only if the field uses them.
+- Each covered state gets a `mock.ts` fixture, a story and at least one test assertion.
+- The scaffold is a working sample: start from it and replace demo content that does not serve the request.
+
+## index.tsx
+
+- `interface Props extends PConnFieldProps`; each extra prop is optional and named exactly like its `config.json` property. Export `withConfiguration(AcmeLibMyField)` (key without underscores).
+- Keep `import '../shared/create-nonce';`. `PConnProps.d.ts` and `create-nonce.ts` live in `src/components/shared/`: never copy or edit them. `PCore` is a global; do not import it.
+- `handleEvent` comes from `import handleEvent from './event-utils'`. If the scaffold did not create `event-utils.ts` (Text does not), copy `.claude/skills/create-dx-component/assets/event-utils.ts` into the component folder once; do not edit it.
+- `propName` is `(pConn.getStateProps() as StateProps).value`.
+- Config booleans can arrive as `'true'`: normalize `readOnly`, `required` and `disabled` with `value === true || value === 'true'`. Numeric config arrives as a string: `parseInt(x, 10)`, with a deliberate `NaN` fallback.
+- `value` can be `null`, which a destructure default misses: `const value = valueProp ?? ''`.
+- Commit with `handleEvent(actions, type, propName, value)`: `'change'` calls `updateFieldValue`, `'blur'` calls `triggerFieldChange`, `'changeNblur'` both.
+
+| Control | While typing | On blur |
+| --- | --- | --- |
+| Text, TextArea, Email, URL | local draft, clear the error | `changeNblur` only if changed |
+| Integer, Decimal, Percentage, Currency | validate draft, keep local | to number or `''`, compare, `changeNblur` |
+| Date, DateTime, Time | commit only a complete valid value | same |
+| Dropdown, RadioButtons, Checkbox | `changeNblur` on change | `validate(value)` (RadioButtons only when there is no value) |
+| Stepper, slider | `changeNblur` on change | none |
+
+- Read the blur value from the callback argument, not React state.
+- Unchanged value: no commit, only `pConn.getValidationApi().validate(value)`. Both empty: `validate('')`, so required still reports.
+- Zero is a value: never `if (!value)` for a number. Clear commits `''`, not `null` or `0`.
+- Guard blur with `!readOnly`. On change call `pConn.clearErrorMessages({ property: propName })`. A local draft needs an effect on `[value]` that resyncs it.
+- `info` is `validatemessage` if non-empty, else the field warning, else `helperText`. `status` is `'error'` with a `validatemessage`, `'pending'` for a suggestion, `'warning'` for a field warning, else `undefined`; never pass `'suggestion-accepted'` to Cosmos.
+- Spread `{...additionalProps}` first; `testId={testId ?? label}`. `hideLabel` maps to `labelHidden`; the label stays the accessible name.
+- `DISPLAY_ONLY` returns early, after all hooks, with no label or input. Empty renders `NoValue`; prefer the Cosmos `*Display` components (`undefined`, not `''`, for `NumberDisplay`, `CurrencyDisplay`).
+- Cosmos-first: the control already handles label, required, disabled, readOnly, status, info and placeholder. Check any Cosmos prop you have not used in `node_modules/@pega/cosmos-react-core/lib/components/<Name>/<Name>.d.ts`.
+- Look up every `PCore` and `pConn` call in [pcore-pconnect-apis.md](./pcore-pconnect-apis.md); use only documented methods.
+- No inline `style={{ ... }}`, `dangerouslySetInnerHTML`, `console`, nested ternaries, `++`, index keys or dead code.
+
+## config.json
+
+- Start from the scaffolded file, never from memory. Add only properties the user confirmed, `label`, `hideLabel` and `readOnly` included.
+- `index.tsx` reads every named property with a safe default, or `check-component.mjs` fails (`VISIBILITY`, `REQUIRED`, `DISABLED`, `READONLY` are platform-handled). Remove a property from config, props and code together.
+- Order: `label`, `hideLabel`, `readOnly`; `GROUP` "Input settings" with `"visibility": "(!readOnly = true)"`; optional "Read-only settings"; `GROUP` "Conditions" (`REQUIRED` shown only when not read-only, `DISABLED`, `VISIBILITY`); collapsible `GROUP` "Advanced" with `testId`.
+- `validate-schema` rejects missing `componentKey`, `name`, `description`, `type`, `subtype` or `properties`, a wrong subtype or casing, a property lacking `name`, `label` or `format`, and duplicates. It does not check `format`: use only scaffold formats.
+- `name` equals `componentKey` and the folder. `SELECT` needs `source: [{ key, value }]`; `GROUP` has no `name`; `NUMBER` defaults are numbers, not strings. Labels are sentence case without `@L`; `@L` marks `defaultConfig` values.
+
+## styles.ts
+
+- Keep the single default-exported `styled.div` wrapper.
+- Add rules only for what Cosmos cannot express (animation, missing states); never layout, text, badges or loading.
+- The theme is undefined here: `useTheme()` in `index.tsx`, pass values as transient props (`$error`).
+- Delete selectors for markup that is gone.
+
+## mock.ts and demo.stories.tsx
+
+- `mock.ts` exports `configProps` (keys mirror `config.json`, resolved, never `@L`) and `stateProps = { value: '.PropertyName' }`.
+- Base story is `Base<InnerFunctionName>`; one story per covered state.
+- Meta `argTypes` gives every `config.json` property a matching control ([storybook-pattern.md](./storybook-pattern.md#controls-argtypes)); hide `getPConnect`.
+- The fake `getPConnect` has exactly the methods the component calls; `updateFieldValue` updates story state; forward `triggerFieldChange` to a story-only arg. Empty callbacks need `/* nothing */`.
+
+## demo.test.tsx
+
+- Query by role and accessible name (`getByRole('textbox', { name: /email/i })`); needing a test id is an accessibility finding. Use `fireEvent` (no `user-event`).
+- One assertion per covered state: label, hidden label with helper text; `required`, `disabled` (`toBeRequired()`, `toBeDisabled()`), `readOnly`; `DISPLAY_ONLY` with and without a value; `validatemessage` replacing `helperText` (assert `toHaveAccessibleDescription`; Cosmos sets `aria-describedby`, not `aria-invalid`); `null`, `''`, `0`, typed over `null`; change does not commit; blur commits `propName` and value; unchanged blur only validates; clear commits `''`; long value.
+- Toggle props with `rerender`; pass story-only args through a `Record<string, unknown>` spread. Never weaken an assertion to pass.
+
+## localizations.json
+
+- Text the field shows itself goes through `pConn.getLocalizationService().getLocalizedText('English text')` and is listed under `fields` in `localizations.json` next to `index.tsx` as `"English text": "English text"`, kept in step with the code.
+- Use whole sentences with `{0}` placeholders; plurals are separate keys; never translate data.
+
+## Open a deep reference only when
+
+| Situation | Read |
+| --- | --- |
+| Dates, time zones, numbers, precision, pickers, URL/email/phone, suggestions, field warnings | [field-behavior.md](./field-behavior.md) |
+| Text-Input, Text-Paragraph, Icon-Button-URL, DateTime, TimeOfDay, Picklist-Autocomplete | [field-subtypes-extra.md](./field-subtypes-extra.md) |
+| A subtype with its own skill | e.g. [text](../../text/SKILL.md), [picklist](../../picklist/SKILL.md) |
+| A config format beyond the scaffold's, visibility, bindings | [config-schema.md](./config-schema.md) |
+| A failing or async test, jsdom stubs, a fuller story fake | [test-pattern.md](./test-pattern.md), [storybook-pattern.md](./storybook-pattern.md) |
+| A Cosmos component you have not used before | [cosmos-components.md](./cosmos-components.md) |
+| Focus, keyboard, announcements, manual checks | [accessibility.md](./accessibility.md) |
+| Placeholders, plurals, formatting, right-to-left | [localization.md](./localization.md) |
+| Full prop list or code skeleton | [props-contract.md](./props-contract.md), [component-patterns.md](./component-patterns.md), [styles-pattern.md](./styles-pattern.md) |
+| A custom control or unclear subtype | [choosing-type-and-subtype.md](./choosing-type-and-subtype.md) |
+| AI-generated content | [state-matrix.md](./state-matrix.md) |
+| A worked example | [field-with-limits-and-validation.md](../cookbooks/field-with-limits-and-validation.md) |
+
+Finish with `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>`; see [cli-workflow.md](./cli-workflow.md).

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

@@ -0,0 +1,68 @@
+# Other Field Subtypes
+
+Six valid Field subtypes have no skill of their own: `Text-Input`, `Text-Paragraph`, `Icon-Button-URL`, `DateTime`, `TimeOfDay` and `Picklist-Autocomplete`. This file gives what is specific to each. The shared rules (commit protocol, empty and zero handling, message precedence) are in [field-behavior.md](./field-behavior.md); props and display modes are in [props-contract.md](./props-contract.md).
+
+Three of them are variants of a base scaffold: the CLI generates `Text-Input` from the `Text` scaffold, `Icon-Button-URL` from `Text-URL`, and `Picklist-Autocomplete` and `Picklist-RadioButtons` from `Picklist`. The `subtype` in `config.json` is what tells App Studio where the author can pick the component. Anything beyond the base scaffold's behavior is **your** implementation, so read the scaffolded `index.tsx` first and change only what the user asked for. Check every Cosmos prop in the installed `.d.ts` before using it.
+
+## Text-Input
+
+A single-line text value. Same as [text](../../text/SKILL.md) with the Cosmos `Input` control and no multi-line option. Do not add a `multiLine` property; if the user needs several lines, the subtype is `Text-Paragraph`.
+
+## Text-Paragraph
+
+A multi-line text value.
+
+| Concern | Guidance |
+| --- | --- |
+| Control | Cosmos `TextArea`. Display mode uses `ParagraphDisplay` (pass `undefined`, not `''`, for an empty value) |
+| Length | Read `maxLength` from `fieldMetadata` when present. Pass `maxLength` and `displayCharCount` to `TextArea`; its `hardStop` prop blocks typing past the limit |
+| Commit | Like Text: keep a local draft, commit on blur only when the value changed. Also call `PCore.getAutosaveUtils().notifyChange(context, pageReference + propName, value)` on change so autosave sees the edit (documented in the catalog) |
+| Size | A paragraph can be long. Test a very long value for layout and for performance |
+| Rich text | Rich text editing is a different control with its own package and an HTML value. Do not build it as a Paragraph, and never render stored HTML with `dangerouslySetInnerHTML` |
+
+## Icon-Button-URL
+
+A web address shown as an icon button that opens the link. It carries all the risk of [url](../../url/SKILL.md): allow only `http:` and `https:`, set `rel='noopener noreferrer'` when opening a new tab, and do not trust the display component to block unsafe schemes. Two additions: an icon-only button **must** have an accessible name (a `label`, never icon alone), and an empty or unsafe value should render no link rather than a dead one.
+
+## DateTime
+
+A date and time stored as a UTC instant, `YYYY-MM-DDTHH:mm:ss.000Z`.
+
+| Concern | Guidance |
+| --- | --- |
+| Conversion | Convert the stored value to the operator's time zone for the input, and back to UTC on commit. The zone comes from `PCore.getEnvironmentInfo().getTimeZone()`; if it is empty and the feature flag `pyEnableDateTimeSystemTimezoneFallback` is on in `getEnvironmentInfo().getFeatureMap()`, use `PCore.getLocaleUtils().getTimeZoneInUse()` |
+| Library | Time-zone arithmetic needs a date library such as `dayjs` with its `utc` and `timezone` plugins. Check whether it is already installed and follow the consent rule in [AGENTS.md](../../../../AGENTS.md) before importing it |
+| Options | `pickerInterval` accepts only 5, 10, 15, 20, 30 or 60 minutes (fall back to 30). `clockFormat` accepts 12 or 24 (fall back to the locale default). Both arrive as strings |
+| Input state | While the Cosmos input reports an invalid or incomplete state, keep the draft and validate; commit only a complete valid value |
+| Read-only | Guard the commit handlers with `!readOnly` |
+| Display | `DateTimeDisplay`. A relative display ("3 hours ago") needs no zone conversion |
+
+## TimeOfDay
+
+A time without a date, stored as `HH:mm:ss`.
+
+| Concern | Guidance |
+| --- | --- |
+| Control | Cosmos `TimeInput`; display `DateTimeDisplay` with the time variant |
+| Commit | On blur only, using the same helper as Date: a complete valid time, otherwise keep the draft and validate |
+| Empty | Pass `undefined` to the control for an empty value |
+| Time zones | A time of day is not an instant. Do not convert it between zones |
+
+## Picklist-Autocomplete
+
+A single choice from a list the user filters by typing.
+
+| Concern | Guidance |
+| --- | --- |
+| Options | As in [picklist](../../picklist/SKILL.md): the platform resolves the options and passes them as props (`datasource`, `listType`, `fieldMetadata`). Do not fetch the list yourself unless the user needs a source the platform does not provide, and then follow [widget-patterns.md](./widget-patterns.md) for the request lifecycle |
+| Control | Cosmos `ComboBox` in single-select mode with a `menu` of items |
+| Two values | Keep the **typed filter text** separate from the **selected item**. Clearing the text deselects the item. Store the key of the selected item, never the text |
+| Loading | Initialize the list on first focus or open, not on mount |
+| Search | Debounce the search (500 ms is typical) and ignore or abort the previous request before sending a new one, so a late response cannot overwrite a newer one. Page long lists. Highlight matches with `createStringMatcher` from Cosmos |
+| Stored key not in the first page | Look the stored key up on its own so the selected label still shows |
+| Empty and error | A search with no match shows an empty message; a failed search shows an error and keeps what the user typed |
+| Accessibility | Keep the combo box's role and arrow-key behavior from Cosmos; do not rebuild it |
+
+## Picklist-RadioButtons
+
+See [radiobuttons](../../radiobuttons/SKILL.md).

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

@@ -0,0 +1,30 @@
+# Localization
+
+Every string a user sees must be translatable, because the same component runs in many languages. This file covers what the scaffolds do and the rules that follow. Anything about how translations reach Pega at runtime is a Pega localization process outside the component: say that you cannot see it and ask the user.
+
+## What the scaffolds do
+
+- A scaffold that shows its own text ships a `localizations.json` next to `index.tsx`. Its shape is a `fields` object whose keys are the English strings, each mapped to the same English string as the default. The Widget `CASE` scaffold, for example, lists `Date`, `Description`, `Performed by` and `Loading case history`.
+- The component asks the platform for the translation of an English string with `pConn.getLocalizationService().getLocalizedText('English text')`. One scaffold uses `PCore.getLocaleUtils().getLocaleValue('English text', category)` with a category name (`'Case'`). Both are in the API catalog.
+- The English text is the lookup key. If no translation exists, the English text is shown.
+
+## Rules
+
+1. **Never hard-code visible text in JSX.** Pass every label, message, button text, empty-state message, error message, `aria-label` and placeholder through `getLocalizedText`.
+2. **Every string you pass must appear in `localizations.json`**, as `"English text": "English text"`. Keep that file in step with the code: a string added in code is added there, and a string removed from code is removed there. A reviewer should be able to diff the two.
+3. **Use a stable, complete sentence as the key.** Do not build a sentence from fragments (`'Showing ' + n + ' of ' + total`), because word order differs between languages. Use a whole string with placeholders that you substitute yourself (for example `'Showing {0} of {1}'` and replace `{0}`, `{1}` after translating). `getLocaleValue` has no placeholder engine.
+4. **Plurals are separate strings.** `'1 item'` and `'{0} items'` are two keys. Do not append an `s`.
+5. **Do not translate values that are data.** A picklist stores the key; show the label the platform provides. Case ids, user names and amounts are not translated.
+6. **Do not store translated text.** Resolve it at render time. When the user switches language, the component receives a new `locale` prop and re-renders, so the translated text must not be cached in state.
+7. **Format numbers, dates and currency with the Cosmos formatters and display components** (`NumberDisplay`, `CurrencyDisplay`, `DateTimeDisplay`, `formatNumber`) and the operator's locale. Do not format by string concatenation.
+8. **Leave room for longer text.** Translations are often 30 to 40 percent longer. Wrap text, avoid fixed widths, and check the longest string in Storybook.
+9. **Labels you put in `config.json` are authoring-time text.** Keep them in sentence case and plain English; only default values that appear to the end user (for example a default heading in `defaultConfig`) use the `@L` prefix to mark them as localizable.
+10. **Right-to-left languages** are handled by Cosmos layout components. Do not hard-code `left` and `right`; use logical properties or Cosmos layout props.
+
+## In tests and stories
+
+Mock `getLocalizationService` to return the key unchanged, so a test asserts the English text. Add one test that passes a non-English mock and checks that the component renders what the service returns instead of its own literal.
+
+## Review checks
+
+[review-component](../../review-component/SKILL.md) item C7 checks that visible text goes through the service. When you review, grep the JSX for string literals and compare the keys used with `localizations.json`.

package/src/ai/project/.claude/skills/create-dx-component/references/pcore-pconnect-apis.md

@@ -0,0 +1,77 @@
+# PCore and PConnect API Reference
+
+This file is an **index**. The authoritative method-by-method catalog (signature, purpose, example, notes) is installed with this project in [`.claude/skills/references/`](../../references/), and the workflow skills (`pconnect-*`) add cookbooks and pitfalls.
+
+**Rules**
+
+1. Before calling any PCore or PConnect method, look up its exact signature in the catalog. Do not write it from memory: names, argument order and return values are easy to get wrong.
+2. Use only the methods documented in the catalog. Treat anything else on `PCore` or `pConn` as unsupported, and tell the user if the task needs it.
+3. Component code reaches PConnect through `props.getPConnect()` and PCore through the global `PCore`. The type of `pConn` comes from `@pega/pcore-pconnect-typedefs`, so `tsc --noEmit` will reject a method that does not exist.
+
+## Look up a method: search, don't read whole files
+
+The catalog files are 5–22 KB each, so search them instead of reading them:
+
+1. Search `.claude/skills/references/` for the bare method name as literal text (for example `getDataPageData` or `isFormValid`). A top-level method is a heading such as `` ### `finishAssignment(containerItemID, options?)` ``; a method on a sub-API object is a backticked first cell in a `| Method | Signature | Purpose |` table row. Do not limit the search to headings, or the table rows are missed.
+2. Read only the matching section: from its heading to the next heading of the same level, or the matching table row and the rows around it.
+3. If you know only the class (`FormUtils`, `EnvironmentInfo`), search for `` (via `PCore.get `` or use the tables below to pick the file.
+4. For call order, cleanup or a sequence of several methods, read the matching `pconnect-*` skill's cookbook instead of assembling it from signatures.
+
+Open the full catalog index, [`.claude/skills/README.md`](../../README.md), only when the search finds nothing and the tables below do not help.
+
+## Where each API is documented
+
+Paths are relative to [`.claude/skills/references/`](../../references/).
+
+### PConnect (`const pConn = getPConnect()`)
+
+| You need to...                                                         | Methods                                                           | Catalog file                                       |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
+| Read the bound property name, config, or inherited props               | `getStateProps`, `getConfigProps`, `getRawMetadata`, `getInheritedProps`, `resolveConfigProps` | `pconnect-state-config.md`      |
+| Read or write values and pass props to children                        | `getValue`, `setValue`, `setInheritedProp`, `setInheritedConfig`  | `pconnect-state-config.md`                         |
+| Know the context, component name, children                             | `getContextName`, `getComponentName`, `getChildren`               | `pconnect-reference-context-component.md`          |
+| Create a child component                                               | `createComponent`                                                 | `pconnect-misc-suggestions-creation.md`            |
+| Clear a validation message, accept or ignore a suggestion              | `clearErrorMessages`, `acceptSuggestion`, `ignoreSuggestion`      | `pconnect-misc-suggestions-creation.md`            |
+| Update a field, submit, cancel, open actions                           | `getActionsApi().updateFieldValue`, `triggerFieldChange`, `finishAssignment`, `cancelAssignment`, `openLocalAction`, ... | `pconnect-actions-api.md` |
+| Validate a value                                                       | `getValidationApi().validate`                                     | `pconnect-validation-api.md`                       |
+| Read case details                                                      | `getCaseInfo().getKey`, `getID`, `getName`, ...                   | `pconnect-case-info-data-info-localization.md`     |
+| Localize text                                                          | `getLocalizationService().getLocalizedText`                       | `pconnect-case-info-data-info-localization.md`     |
+| Edit rows of a list property                                           | `getListActions()`                                                | `pconnect-list-actions.md`                         |
+| Manage containers                                                      | `getContainerManager()`                                           | `pconnect-container-manager.md`                    |
+
+### PCore (global)
+
+| You need to...                                              | Accessor                                                     | Catalog file                                                                  |
+| ----------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Load a data page or data view                               | `PCore.getDataApiUtils().getData`, `PCore.getDataPageUtils()` | `pcore-rest-data-messaging.md`, `pcore-rest-data-details.md`                  |
+| Call a REST endpoint                                        | `PCore.getRestClient()`                                      | `pcore-rest-data-messaging.md`, `pcore-rest-data-details.md`                  |
+| Publish or subscribe to events                              | `PCore.getPubSubUtils()`, `PCore.getEvents()`                | `pcore-rest-data-messaging.md`, `pcore-messaging-details.md`                  |
+| Show or clear messages                                      | `PCore.getMessageManager()`                                  | `pcore-rest-data-messaging.md`, `pcore-messaging-details.md`                  |
+| Use constants such as `CASE_INFO`                           | `PCore.getConstants()`                                       | `pcore-misc-utilities.md`                                                     |
+| Read operator, locale or environment details                | `PCore.getEnvironmentInfo()`, `PCore.getLocaleUtils()`       | `pcore-environment-locale-namespace.md`, `pcore-environment-info-details.md`  |
+| Work with cases, containers, attachments, feed, tags, users | `PCore.getCaseUtils()`, `getContainerUtils()`, `getAttachmentUtils()`, `getFeedUtils()`, `getTagUtils()`, `getUserApi()` | `pcore-case-collaboration-genai.md`, `pcore-case-collaboration-details.md` |
+| Form helpers and error handling                             | `PCore.getFormUtils()`, `PCore.getErrorHandler()`            | `pcore-misc-utilities.md`, `pcore-misc-details.md`                            |
+| Build deep links, change locale                             | `PCore.getSemanticUrlUtils()`, `PCore.getLocaleUtils()`      | `pcore-rest-data-messaging.md`, `pcore-environment-locale-namespace.md`       |
+| GenAI assistant, analytics, personalization                 | `PCore.getGenAIAssistantUtils()`, `getAnalyticsUtils()`, `getPersonalizationUtils()` | `pcore-case-collaboration-genai.md`, `pcore-analytics-genai-details.md` |
+
+For anything not listed here, search the catalog for the method name as described above.
+
+## Which skill covers the workflow
+
+| Task                                                                      | Skill                              |
+| ------------------------------------------------------------------------- | ---------------------------------- |
+| Submit, validate, cancel or delete assignments and cases; attachments     | `pconnect-assignment-lifecycle`    |
+| Field validation, dependent fields, autosave, persisting widget UI state  | `pconnect-forms-and-fields`        |
+| Data page subscriptions, pub/sub, real-time updates                       | `pconnect-data-subscriptions`      |
+| Participants, followers, related cases, tags, feed                        | `pconnect-case-collaboration`      |
+| Repeating rows, list view personalization, container lifecycle            | `pconnect-lists-and-views`         |
+| Deep links, locale switching, GenAI assistant                             | `pconnect-navigation-locale-genai` |
+
+Cross-cutting guidance (testing, error handling, performance, security, accessibility) is in [`.claude/skills/best-practices/`](../../best-practices/).
+
+## Official documentation
+
+- [Using PCore and PConnect public APIs](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/using-pcore-pconnect-public-apis.html)
+- [Accessing APIs from the PConnect object](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/accessing-apis-pconnect-object.html)
+- [Accessing APIs from the PCore object](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/accessing-apis-pcore-object.html)
+- [Using type definitions for PCore and PConnect APIs](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/using-type-definitions-pcore-pconnect-apis.html)

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

@@ -0,0 +1,57 @@
+# Presentation essentials
+
+Read this instead of the deep references for a typical presentation. Open a deep reference only for the cases listed at the end.
+
+## Before you code
+
+- There are no Presentation rows in the state matrix: use the Widget rows for the data the case view shows and the Template rows for its regions. Cover optional props being absent (`subheading`, `banners`, `utilities` and similar); long content and narrow width usually apply too.
+- Each covered state gets a `mock.ts` fixture, a story and at least one test assertion.
+- Start from the scaffolded files; the scaffold is a working sample, replace demo content that does not serve the request. Its plain-HTML markup is a placeholder to replace with Cosmos components.
+
+## index.tsx
+
+- Props are `CaseViewProps` from `@pega/cosmos-react-work` (`CASEVIEW`) or `@pega/cosmos-react-wss` (`WSSCASEVIEW`). Read `node_modules/@pega/cosmos-react-work/lib/components/CaseView/CaseView.types.d.ts` (for `WSSCASEVIEW`, the same path under `node_modules/@pega/cosmos-react-wss/lib/components/CaseView/`; if it is missing, list that folder) before using a prop.
+- No `getPConnect`, `PCore`, `getActionsApi`, `getValidationApi` or any PCore/PConnect API; the lint rule `no-pcore-pconnect-in-presentation` rejects them. If the props do not carry the data, the component should be a Widget.
+- Pure render: output is a deterministic function of props. No data fetching or side-effecting effects; local UI state (open, hover) is fine.
+- Keep `export default withConfiguration(...)`. The scaffold has no `create-nonce` import: add `import '../shared/create-nonce';` if you keep `styled-components` (copy [create-nonce.ts](../assets/create-nonce.ts) into `src/components/shared/` if missing).
+- Cosmos-first (`Flex`, `Text`, `Status`, `Tag`, `Count`, `Icon`, `FieldValueList`, `Tabs`, ...). Check any new Cosmos prop in its `.d.ts`.
+- No inline `style={{ ... }}`, `dangerouslySetInnerHTML`, `console`, dead code, secrets, tokens or per-environment URLs (`check-component.mjs` fails).
+
+## config.json
+
+- Keep `type: "Presentation"` and the scaffolded `subtype`; `validate-schema` rejects any subtype other than `CASEVIEW` and `WSSCASEVIEW`.
+- `"properties": []` by default. Add a property only if the user wants a designer-configurable setting, and make `index.tsx` read it.
+
+## styles.ts
+
+- Keep the single default-exported `styled.div` wrapper; add rules only for what Cosmos cannot express.
+- The theme is undefined here: `useTheme()` in `index.tsx`, pass values as transient props.
+
+## mock.ts and demo.stories.tsx
+
+- `mock.ts` holds sample case view props; extend it when the component reads more props.
+- Stories render the component with those props; no `getPConnect` or `PCore` fakes are needed. One story per covered state.
+
+## demo.test.tsx
+
+- Assert on rendered output only, querying by role and accessible name first. Use `fireEvent` (no `user-event`).
+- One assertion per covered state, including a render with the optional props absent. Never weaken an assertion.
+
+## localizations.json
+
+- The scaffold ships one listing its visible strings under `fields` as `"English text": "English text"`. Keep it in step with the text the component renders.
+
+## Open a deep reference only when
+
+| Situation | Read |
+| --- | --- |
+| The full Presentation procedure | [presentation](../../presentation/SKILL.md) |
+| The Widget and Template state rows | [state-matrix.md](./state-matrix.md) |
+| A Cosmos component you have not used, theme palette keys | [cosmos-components.md](./cosmos-components.md), [styles-pattern.md](./styles-pattern.md) |
+| A failing test | [test-pattern.md](./test-pattern.md) |
+| Headings, focus, keyboard, manual checks | [accessibility.md](./accessibility.md) |
+| Localization rules | [localization.md](./localization.md) |
+| A config property | [config-schema.md](./config-schema.md) |
+| The full skeleton or the props contract | [component-patterns.md](./component-patterns.md), [props-contract.md](./props-contract.md) |
+
+Finish with `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>`; see [cli-workflow.md](./cli-workflow.md).

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

@@ -0,0 +1,182 @@
+# Custom Component Types and the Props Contract
+
+> Part of the [create-dx-component skill](../SKILL.md). PCore/PConnect signatures are in the [API catalog](./pcore-pconnect-apis.md).
+
+A Constellation custom component is a React function component wrapped with `withConfiguration` from `@pega/cosmos-react-core`. At runtime Constellation renders it with a **props object** built from three sources:
+
+1. The values of the properties declared in the component's `config.json` (`properties[].name`), resolved for the current case, page or view.
+2. Standard field props that Constellation adds for field components (`value`, `required`, `readOnly`, `validatemessage`, ...).
+3. `getPConnect`, a function that returns the component's `PConnect` object. This is the entry point to the PConnect and (through the global `PCore`) PCore APIs documented in this skills folder.
+
+Stories and tests build the same props object by hand (see [test-pattern.md](./test-pattern.md)).
+
+## Choosing the component type
+
+| You want to...                                                                    | Type and subtype                                      | Gets `getPConnect` | Gets `children` |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------ | --------------- |
+| Edit or display a single property value in a new way                              | `Field` + the matching data subtype                   | yes                | no              |
+| Arrange the fields of a form or details view (columns, groups, sections)          | `Template` + `FORM` or `DETAILS`                      | yes                | yes             |
+| Arrange fields in named regions the designer fills in                             | `Template` + `FORM-region` or `DETAILS-region`        | yes                | yes (per region) |
+| Lay out a whole page from regions                                                 | `Template` + `PAGE`                                   | yes                | yes             |
+| Add a self-contained panel that loads its own data (a list, a chart, a summary)   | `Widget` + `PAGE` (a page) or `CASE` (a case view)    | yes                | no              |
+| Replace how a case view is rendered from data passed in as props                  | `Presentation` + `CASEVIEW` or `WSSCASEVIEW`          | no                 | no              |
+
+Pick the **subtype that matches the property's data type** for a field (`Integer`, `Date`, `Picklist`, `Boolean`, ...). The scaffold for that subtype already handles the display modes and value types that data type needs.
+
+## Props common to every component with `getPConnect`
+
+```typescript
+import type { PConnect } from '@pega/pcore-pconnect-typedefs';
+
+interface PConnProps {
+  getPConnect: () => typeof PConnect; // always present at runtime
+}
+```
+
+The scaffolded `PConnProps.d.ts` (in `src/components/shared/` in library mode) defines `PConnProps` and `PConnFieldProps`. Extend `PConnFieldProps` with the extra props your `config.json` declares.
+
+## Field components
+
+`PConnFieldProps` provides:
+
+| Prop                                    | Meaning                                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `value`                                 | Current value of the bound property                                                                       |
+| `label`, `hideLabel`, `helperText`      | Label text, whether to hide it visually, and help text                                                    |
+| `placeholder`                           | Placeholder text                                                                                          |
+| `required`, `disabled`, `readOnly`      | Edit state. These can arrive as strings (`'true'`), so normalize them, as the scaffolds do                |
+| `validatemessage`                       | Validation error text. A non-empty string means the field is in error                                     |
+| `status`                                | Optional status string (for example `'error'`, `'success'`, `'pending'`)                                  |
+| `displayMode`                           | How to render: editable when empty, or read-only variants (see below)                                     |
+| `testId`                                | Value for `data-testid` / the design-system `testId` prop                                                 |
+| `additionalProps`, `fieldMetadata`      | Extra metadata passed by the platform (shape depends on the subtype)                                      |
+
+### Display modes
+
+The scaffolded fields branch on `displayMode`:
+
+- `'DISPLAY_ONLY'`: render just the value, no label or input.
+- anything else (including empty): render the editable control.
+
+Always handle `DISPLAY_ONLY`. A field that only renders an input looks broken in details views and tables. Older view metadata and the authoring preview can still pass `'LABELS_LEFT'` (a label/value pair); the runtime itself only distinguishes `DISPLAY_ONLY`, and the scaffolds no longer branch on `LABELS_LEFT` or `'STACKED_LARGE_VAL'`.
+
+### Reading and writing the value
+
+```typescript
+const pConn = getPConnect();
+const actions = pConn.getActionsApi();
+const stateProps = pConn.getStateProps() as { value: string }; // e.g. { value: '.FirstName' }
+const propName = stateProps.value; // the property reference to write to
+
+// while the user types: update the value in the store
+actions.updateFieldValue(propName, newValue);
+// when the user leaves the field (blur) or picks an option: commit and trigger dependent logic
+actions.triggerFieldChange(propName, newValue);
+```
+
+The convention used by every scaffolded field: call `updateFieldValue` on change, `triggerFieldChange` on blur, and both on change for controls with no blur moment (selects, checkboxes, radio buttons). Signatures are in [pconnect-actions-api.md](../../references/pconnect-actions-api.md).
+
+Read-only data and expressions use `getStateProps()`; see [pconnect-state-config.md](../../references/pconnect-state-config.md).
+
+### Validation and error messages
+
+- Show `validatemessage` when it is a non-empty string (the scaffolds set the design-system field `status` to `'error'` and pass the message as `info`).
+- Client-side validation: `pConn.getValidationApi().validate(...)` (see [pconnect-validation-api.md](../../references/pconnect-validation-api.md)); clear a message with `pConn.clearErrorMessages({ property })` (see [pconnect-misc-suggestions-creation.md](../../references/pconnect-misc-suggestions-creation.md)).
+
+## Template components (FORM, DETAILS, PAGE)
+
+Templates receive `children`: React elements for the child components in the template's regions. Render them where they belong in your layout instead of recreating them.
+
+```typescript
+const { children = [], NumCols = '1', label, showLabel, getPConnect } = props;
+const inherited = getPConnect().getInheritedProps(); // props inherited from the parent view (readOnly, displayMode, ...)
+```
+
+- `children` can be a single element, an array or nested arrays. Normalize with `[props.children].flat(Infinity).filter(isValidElement)` when you need to inspect them, and guard against an empty or undefined value.
+- `FORM` and `DETAILS` templates lay out `children` in a grid with a configurable number of columns (`NumCols`).
+- `*-region` templates declare named regions in `config.json` (`A`, `B`, ... with format `CONTENTPICKER`); `children` has one entry per region.
+- `DETAILS` marks child fields read-only through `child.props.getPConnect().setInheritedProp('readOnly', true)` and `setInheritedProp('displayMode', 'DISPLAY_ONLY')`.
+- Inherited-prop methods are in [pconnect-state-config.md](../../references/pconnect-state-config.md); child components and `createComponent` are in [pconnect-reference-context-component.md](../../references/pconnect-reference-context-component.md) and [pconnect-misc-suggestions-creation.md](../../references/pconnect-misc-suggestions-creation.md).
+
+## Widget components
+
+A widget owns its data. The scaffolds fetch data in `useEffect` through `PCore` and render it with design-system components:
+
+```typescript
+const pConn = getPConnect();
+const context = pConn.getContextName();
+const caseID = pConn.getValue(PCore.getConstants().CASE_INFO.CASE_INFO_ID, '');
+
+PCore.getDataApiUtils()
+  .getData('D_pyWorkHistory', { dataViewParameters: { CaseInstanceKey: caseID } }, context)
+  .then((response) => { /* map response.data.data to rows */ });
+```
+
+`PCore.getConstants()` is documented in [pcore-misc-utilities.md](../../references/pcore-misc-utilities.md). Rules for widgets: track a loading state, handle `response.data.data === null`, handle rejection, and re-fetch only when the inputs (`context`, `caseID`) change. See [pcore-rest-data-details.md](../../references/pcore-rest-data-details.md) and the [error handling](../../best-practices/error-handling-and-resiliency.md) and [performance](../../best-practices/performance-and-efficiency.md) guides.
+
+Use `pConn.getLocalizationService().getLocalizedText('...')` for user-visible strings (see [pconnect-case-info-data-info-localization.md](../../references/pconnect-case-info-data-info-localization.md)). Widget scaffolds include a `localizations.json` file for translations.
+
+## Presentation components
+
+`CASEVIEW` and `WSSCASEVIEW` components do not use `getPConnect` or `PCore`. They receive everything as props whose type comes from the design system (`CaseViewProps` from `@pega/cosmos-react-work`, or from `@pega/cosmos-react-wss` for `WSSCASEVIEW`). Implement the rendering only; the type tells you which props exist.
+
+## Rules that apply to every type
+
+1. Export the component as `export default withConfiguration(MyComponent)`.
+2. Keep `import '../shared/create-nonce';` in `index.tsx` (Presentation scaffolds do not include it). It sets the webpack nonce for styles.
+3. Render through the design-system (`@pega/cosmos-react-core`, `-work`, `-wss`) components. They provide accessibility and theming. Wrap the output in the scaffolded `styled-components` wrapper from `styles.ts`.
+4. Every prop you read must be declared in the props interface **and** exist as a `config.json` property (or be a standard prop above). See [config-schema.md](./config-schema.md).
+5. Do not use PCore or PConnect members that are not documented in this folder. Treat them as unsupported.
+6. Do not read or write the DOM or `window` for application data. Use the PCore and PConnect APIs.
+
+## `index.tsx` file rules
+
+### Required shape
+
+
+```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 {
+  // one entry per extra property in config.json, all optional
+}
+
+function AcmeLibComponentName(props: Props) { ... }
+
+export default withConfiguration(AcmeLibComponentName);
+```
+
+- The inner function name is `AcmeLib<ComponentName>` — PascalCase, matching `config.json` `name` with underscores removed.
+- `import '../shared/create-nonce';` is side-effect only (the scaffold generates it in `src/components/shared/`). Never remove it, never bind it to a variable.
+- Always default-export through `withConfiguration()`.
+- `Props` extends `PConnFieldProps`; every added prop is optional and mirrors a `config.json` property name exactly.
+- Never edit `PConnProps.d.ts`, `create-nonce.ts`, or `event-utils.ts` — they are contract files.
+
+### Cosmos-first in this file
+
+
+The canonical rule lives in [AGENTS.md](../../../../AGENTS.md) and loads on every request. What it means *in this file*: the component's rendered tree must be Cosmos components. `StyledWrapper` from `./styles` is a positioning shell, not a layout system — put `Flex`/`Grid` inside it, not `<div className='row'>`.
+
+**Never use inline `style={{ ... }}` here.** Custom CSS belongs in `styles.ts`.
+
+**Verify every Cosmos prop you have not used before** by reading `node_modules/@pega/cosmos-react-core/lib/components/<Name>/<Name>.d.ts`. Prop names here are often not what they sound like — `Banner` needs an array, `EmptyState` uses `message` not `title`, `Tag` needs `children` not `label`, and `Divider` / `Badge` / `IconButton` / `Tab` do not exist. The known traps are in [cosmos-components.md](../../../../.claude/skills/create-dx-component/references/cosmos-components.md).
+
+To read a Cosmos theme value, call `useTheme()` in this file and pass the value into the styled component as a prop — the theme does not reach `styles.ts` on its own.
+
+### Lint constraints that bite here
+
+
+- `no-console` — no `console.*`
+- `no-plusplus` — use `+= 1`
+- `no-nested-ternary`, `no-lonely-if`
+- `func-names` — no anonymous function expressions
+- `radix` — `parseInt(x, 10)`
+- `react/no-array-index-key` — use a stable key, not the index
+- `react/button-has-type` — every `<button>` needs an explicit `type`
+- `@typescript-eslint/no-unused-vars` — every import, variable, state value, helper, and interface field must be referenced. Delete anything that is not.
+
+`any` and `@ts-ignore` are permitted. `PCore` is a global — do not import it.

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

@@ -0,0 +1,102 @@
+# State Matrix
+
+Decide which states a component covers **before** writing code, and show the list to the user with the contract. The same list then drives `mock.ts`, the stories and the tests, so a state that is not in the matrix is not built, not demonstrated and not tested.
+
+Cover every row marked *applicable* for the type. Mark a row *not applicable* with a reason instead of silently skipping it.
+
+## How to use it
+
+1. Copy the rows for the component type into the plan and mark each *applicable* or *not applicable*.
+2. For each applicable row, state what is visible, what is interactive and what is announced.
+3. Give each applicable row one `mock.ts` fixture and one story (see [storybook-pattern.md](./storybook-pattern.md)).
+4. Give each applicable row at least one assertion in `demo.test.tsx` (see [test-pattern.md](./test-pattern.md)).
+
+Do not model states as independent booleans (`isLoading`, `hasError`, `isEmpty`) when contradictory combinations are possible. Use one status value, for example `'loading' | 'ready' | 'empty' | 'error'`.
+
+## Field
+
+A Field receives its state from the platform as props ([props-contract.md](./props-contract.md)). The matrix is about how the control reacts to those props.
+
+| State | Platform input | Check |
+| --- | --- | --- |
+| Empty | `value` is `''` or `undefined` | Control stays controlled (default to `''`); placeholder or empty display is meaningful |
+| Populated | `value` set | Formatted consistently; the stored value is not the formatted text |
+| Editing | user input | Change goes through `handleEvent`; commit happens on the event the contract names (change or blur) |
+| Invalid | `validatemessage` is a non-empty string | Error is visible, tied to the control and not conveyed by color alone |
+| Required | `required` | Required status is shown without color alone |
+| Disabled | `disabled` | Not focusable or operable; the reason is clear when the label alone does not explain it |
+| Read-only | `readOnly` | Value readable; does not look editable |
+| Display only | `displayMode === 'DISPLAY_ONLY'` | Just the value, no label or input (details views and tables) |
+| Long or malformed value | very long string, wrong type, `null` | Layout holds and nothing throws |
+| Narrow width | small container | Label, control, helper text and error reflow in order |
+| Suggestion available / accepted | platform suggestion, `status` | Pending status shown only when the suggested value is among the options; accepted and rejected paths both clear it |
+| Field warning | `showFieldMessage` with `messageConfig` | Shown when enabled, suppressed when read-only, hidden when its condition is false |
+| Unchanged or empty blur | blur with the stored value | No commit; `validate` still runs so a required field reports its error |
+
+Add `status` (`'error'`, `'success'`, `'pending'`) rows only if the component reads it.
+
+## Widget
+
+A Widget owns its data, so the matrix is mostly about the request lifecycle. Keep these cases distinct: they are often merged and then misreported.
+
+| State | Check |
+| --- | --- |
+| Initial loading | Placeholder (`Progress` or a skeleton) keeps the layout stable |
+| Loaded | Data and available actions are clear |
+| Empty | Wording separates "no results" from "not configured" |
+| Error | Message is actionable, hides internals, and offers a retry when retrying can help |
+| Refreshing | Existing content stays visible while new data loads |
+| Stale response | A late response for an older request is ignored |
+| Action pending | Duplicate activation is blocked and progress is announced |
+| Partial data | One failing section does not blank the others (only if the widget has sections) |
+| Permission-limited | Restricted content is omitted and not reported as an error (only if the data source can restrict) |
+| Failed mutation | A message is shown in a `Banner`, the control is re-enabled, and the list is unchanged |
+| Late response | A response for an older request or an unmounted widget is ignored |
+| Offline | A visible offline message accompanies Retry; no spinner that cannot finish |
+| Long content | Lists, labels and actions stay usable |
+| Narrow width | Information hierarchy survives; actions stay reachable |
+
+For the fetch itself follow the [data widget cookbook](../cookbooks/build-a-data-widget.md). Cancel or ignore a request on unmount and on a context change.
+
+## Template
+
+A Template arranges `children`, so the matrix is about composition.
+
+| State | Check |
+| --- | --- |
+| All regions populated | Reading order is clear |
+| Optional region empty | Layout collapses or keeps space on purpose |
+| Required region empty | The problem is visible, not a blank gap |
+| One child unavailable or unsupported | The other regions keep working |
+| Long child content | Wraps, scrolls or reflows predictably |
+| Narrow width | Regions stack in the intended semantic order |
+| Wide width | Extra space is handled without fixed positioning |
+| All children of a region hidden | The region and its heading disappear; no empty titled section |
+| Read-only parent | Children are forced to `readOnly` and `DISPLAY_ONLY`, and none show an input |
+| Active tab becomes hidden or removed | Falls back to the first visible tab; no dangling id |
+| Nested template | Inherits or overrides the parent column count on purpose |
+| Missing or string config | `NumCols` as `'2'`, absent or non-numeric falls back to one column |
+
+## Presentation
+
+Use the Widget rows for the data the case view loads and the Template rows for its regions.
+
+## AI-assisted content
+
+Add these rows to a Widget or Field that shows or acts on generated content, in addition to the rows above. See the best-practices notes on GenAI integration in the API catalog.
+
+| State | Check |
+| --- | --- |
+| Generating | A progress indication and partial output that can be read. Announce start and finish politely, not every update |
+| Complete | The result is shown with a clear marker that it is machine-generated |
+| Cancelled | The user can stop it, and the interface returns to a usable state with nothing half-applied |
+| Failed or unavailable | An actionable message, a retry, and the rest of the component still works |
+| Refused or blocked | A plain explanation instead of a blank or an error code |
+| Low confidence or uncertain | Flagged, not presented as fact |
+| Awaiting review | Nothing takes effect until a person accepts it, when the requirements say so |
+| Feedback | The user can accept, reject or rate the result |
+| Untrusted output | Rendered as plain text or sanitized; never as raw HTML |
+
+## Recording the result
+
+Write the matrix as a table in the plan you show the user, with a column for the story name that will demonstrate each row. After building, every row marked applicable must have a story and an assertion. If one cannot be built (for example a state the mocked PConnect cannot reproduce), say so in the report instead of dropping it.