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

package/src/ai/project/.claude/skills/plan-dx-component/references/plan-template.md

@@ -0,0 +1,76 @@
+# Component Plan Template
+
+Fill in every section that applies. Write "not applicable" with a reason instead of leaving a section out. Keep it short enough to read in one sitting; the point is a decision, not a document.
+
+## 1. Summary
+
+One paragraph: what the component does and for whom. Whether it is a plan from requirements or a port, and from what source.
+
+## 2. Fit and type
+
+- Buildable as a custom DX component: yes, partly, or no, and why.
+- Type and subtype, and the reason (for a Field, the type of the stored value).
+- Anything that does not fit, and the closest alternative.
+
+## 3. Contract
+
+| Item | Decision |
+| --- | --- |
+| Name and label | `<Org>_<Library>_<Name>`, and the label shown in App Studio |
+| Where it appears | The view, page or placement |
+| Data in | The bound property, the data page, or the props |
+| Data out | What it writes back, and when it commits |
+| Read-only and display-only behavior | |
+| Edge values | Empty, `null`, zero, very long, malformed |
+
+## 4. Authoring properties
+
+| Property | Label | Format | Default | Why the designer needs it |
+| --- | --- | --- | --- | --- |
+
+Start with the smallest set that makes the component usable.
+
+## 5. States
+
+Choose the applicable rows from [state-matrix.md](../../create-dx-component/references/state-matrix.md). For each: what is shown, what can be done, what is announced.
+
+## 6. Building blocks
+
+- Cosmos components and what each is for (see [design-system-mapping.md](./design-system-mapping.md)).
+- PCore and PConnect methods needed, each found in the API catalog.
+- Anything custom, and why Cosmos does not cover it.
+
+## 7. Quality and compliance
+
+- The accessibility target and any regional rules, as stated by the user or marked as a proposed default.
+- Languages (including right-to-left), supported browsers and devices, performance and data-size expectations, privacy and audit needs.
+
+- Accessibility: names, keyboard path, focus, announcements ([accessibility.md](../../create-dx-component/references/accessibility.md)).
+- Localization: the visible strings ([localization.md](../../create-dx-component/references/localization.md)).
+- Tests and stories: one per state, plus the edge values.
+
+### AI-assisted content (only if the component uses AI)
+
+Source of the content and what is sent to it; how it is labeled as machine-generated; whether a person must approve it; stop, retry and feedback; the states from [state-matrix.md](../../create-dx-component/references/state-matrix.md); how model output is sanitized before rendering.
+
+## 8. Dependencies and risks
+
+| Item | Needed for | In Cosmos or the browser? | Consent |
+| --- | --- | --- | --- |
+
+Plus any platform behavior that could not be verified.
+
+## 9. Open questions
+
+Numbered, each with who can answer it.
+
+## 10. Acceptance criteria and trace
+
+A short list the user can check: observable behavior, not implementation. Keep the user's own wording where they gave criteria, and map each criterion to the test that will prove it.
+
+| Requirement or criterion | Source (file, link, image, or the message) | Decision | Test |
+| --- | --- | --- | --- |
+
+## 11. Size
+
+Small, medium or large, and the biggest uncertainty behind that estimate.

package/src/ai/project/.claude/skills/plan-dx-component/references/requirements-template.md

@@ -0,0 +1,88 @@
+# Requirements Template
+
+Copy this into a file (for example `requirements/QuantityField.md`) and fill in what you know. **Leave anything you do not know blank**: the assistant will ask about it, or propose a default for you to approve. You can also ask the assistant to interview you and write the file for you.
+
+You can attach images, paste links, or name a design system anywhere below.
+
+## 1. What is it for?
+
+- What problem does it solve, and for whom?
+- In one or two sentences, what should the user be able to do?
+
+## 2. Where will it appear?
+
+- In which case type, step, page or dashboard?
+- Is it one input for one value, a block that shows its own data, a layout that arranges other fields, or a replacement for the whole case view?
+- Does it appear in more than one place?
+
+## 3. Data
+
+- What value or data does it show or change? Give the property name if you know it.
+- Where does the data come from (a case property, a data page, something else)?
+- Give two or three **example values**, including an empty one and an unusual one.
+- If it changes data, when should the change be saved (as the user types, when they leave the field, on a button)?
+
+## 4. Behavior
+
+- What should happen when the user interacts with it? List the actions in order.
+- What is allowed, and what must be refused (for example, only whole numbers from 1 to 999)?
+- What error message should the user see, in your own words?
+
+## 5. States
+
+Say what should be shown in each state you care about. Skip the ones that do not apply.
+
+| State | What the user sees and can do |
+| --- | --- |
+| Normal | |
+| Empty | |
+| Loading | |
+| Error | |
+| Read-only or display-only | |
+| Disabled | |
+| Success | |
+| Very long or unusual content | |
+
+## 6. Look and feel
+
+- Screenshots, mockups or a sketch: attach them or give the file names, and say what each one shows.
+- Public links to something similar (documentation, a demo, an example): paste them. Only public pages can be read. For a private ticket, wiki page or document, paste the relevant text or save an export into the project.
+- Code or a prototype from a design tool, or a design file export: attach it and say what it should and should not decide.
+- A design system or library you want it to resemble (name, version, component): the assistant will map it onto the Pega design system and tell you what will look different.
+- Anything about the look that is a hard requirement.
+
+## 7. What should the app designer be able to configure in App Studio?
+
+List the settings you would like (for example a minimum, a label, a color map), and a default for each.
+
+## 8. Quality and compliance
+
+- Accessibility target (for example WCAG 2.2 level AA) and any regional rules that apply to you. Leave blank if you do not know; the assistant will propose a default and say so.
+- Languages, including any right-to-left language.
+- Browsers and devices it must work on.
+- Performance expectations, and the largest amount of data it must handle.
+- Privacy and data-handling rules, and whether it must leave an audit trail.
+
+## 8a. Does it use AI?
+
+Skip this if it does not generate or act on generated content.
+
+- What does the AI produce or decide (suggestions, a summary, an answer, an action)?
+- Where does it come from, and what data is sent to it?
+- How should the user know it is machine-generated, and must a person approve it before it has an effect?
+- Can the user stop it, retry it and give feedback?
+- What should happen when it is slow, wrong, refused or unavailable?
+
+## 9. Limits
+
+- What must it **not** do?
+- Which libraries are you willing, or not willing, to use?
+- Deadline or size expectations, if any.
+
+## 10. How will you know it works?
+
+A short list of things you will check. Given/when/then sentences are ideal because each one becomes a test. For example "typing 0 shows an error", "clearing the field leaves it empty", "it looks right in a details view".
+
+## 11. Anything else
+
+Context, history, related components, links to tickets.

package/src/ai/project/.claude/skills/presentation/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: presentation
+description: 'Scaffold and implement a Pega DX **Presentation** component. In this tooling a Presentation component replaces how a whole case view is rendered (subtypes CASEVIEW and WSSCASEVIEW): it receives everything as props and has no access to PCore or PConnect. Use when: the user wants to restyle or restructure the case view page. NOT for badges, status pills, formatters or other read-only displays — use a Field (bound to a property) or a Widget (standalone block) for those.'
+argument-hint: 'Describe the case view change (e.g., "a case view with a compact header and the tabs on the left")'
+---
+
+# Create Presentation Component Skill
+
+## When to Use
+
+- The user wants to **replace how a case view is rendered**: header, summary fields, tabs, stages, tasks, banners, utilities.
+- The two supported subtypes are `CASEVIEW` (props type `CaseViewProps` from `@pega/cosmos-react-work`) and `WSSCASEVIEW` (props type `CaseViewProps` from `@pega/cosmos-react-wss`).
+
+Do NOT use this skill for:
+
+- an input or a read-only value bound to a case property, such as a badge, status pill, formatted number or icon (use `field` and handle `DISPLAY_ONLY`),
+- a standalone block that shows its own data (use `widget`),
+- a layout container (use `template`).
+
+`config.json` `type: "Presentation"` accepts only the subtypes `CASEVIEW` and `WSSCASEVIEW`; any other subtype fails `validate-schema`.
+
+## What a Presentation component is
+
+A Presentation component is a **pure render of props**. The platform passes every piece of the case view (heading, summary fields, tabs, stages, tasks, banners, utilities, expand/collapse state and callbacks) as props whose type comes from the design system. There is no `getPConnect`, and the project's lint rule `no-pcore-pconnect-in-presentation` rejects any use of `PCore` or `getPConnect` in a component whose `config.json` has `type: "Presentation"`.
+
+Consequently:
+
+- Do not call `getPConnect`, `PCore`, `getActionsApi`, `getValidationApi` or any PCore/PConnect API. If the requirement needs data the props do not carry, the right component type is a Widget.
+- Do not fetch data or run side-effecting effects. Local UI state (open/closed, hover) is fine.
+- Render from the props the type defines. Read the type before using a prop: `node_modules/@pega/cosmos-react-work/lib/components/CaseView/CaseView.types.d.ts` (or the `@pega/cosmos-react-wss` equivalent for `WSSCASEVIEW`).
+
+## Procedure
+
+The repo-wide rules (gallery reuse, contract approval and its layout, authoring properties, consent, Cosmos first, no dead code) are in `AGENTS.md` and are not repeated here.
+
+### Step 0: Check the UI Gallery
+
+Follow [ui-gallery-reuse.md](../create-dx-component/references/ui-gallery-reuse.md).
+
+### Step 1: Agree the contract
+
+Use the approval layout from `AGENTS.md`. The draft states:
+
+- **Subtype**: `CASEVIEW` or `WSSCASEVIEW`
+- **Name**: PascalCase; the component key is `<Org>_<Library>_<Name>`
+- **What changes**: which parts of the case view are rearranged or restyled, and what keeps the default behavior
+- **Properties**: none by default (`"properties": []`); add one only if the user wants a designer-configurable setting
+
+### Step 2: Scaffold
+
+`npm run create -- Presentation CASEVIEW <Name> "<Label>" 1.0.0 <Library> "<description>" <Organization>`
+
+Use `WSSCASEVIEW` instead of `CASEVIEW` for the Web Self Service variant. See [cli-workflow.md](../create-dx-component/references/cli-workflow.md) for the full command forms.
+
+### Step 3: Implement
+
+Implement every scaffolded file from [presentation-essentials.md](../create-dx-component/references/presentation-essentials.md): pure render from the props, no PCore or `getPConnect`, Cosmos instead of the scaffold's plain-HTML placeholder, the `create-nonce` import if you keep `styled-components`, and a test with the optional props absent.
+
+### Step 4: Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` (`--no-build` while fixing), fix every failure, and paste the final table into your report.

package/src/ai/project/.claude/skills/publish-library/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: publish-library
+description: 'Connect to a Pega Infinity server and publish a DX component library — authentication, `tasks.config.json` server settings, SSL keys, library versions, and the store/export lifecycle. Use when: the user wants to authenticate, publish, version, store, restore, export, or import a component library, or is debugging a failed `npm run publish` or `npm run authenticate`.'
+argument-hint: 'Describe the goal (e.g. "publish the current library version" or "authenticate against a new Infinity server")'
+---
+
+# Publish DX Component Library Skill
+
+Building and testing a component is covered by [validate-component](../validate-component/SKILL.md). This skill starts once the component builds clean and needs to reach a Pega server.
+
+## This repo is in Library mode
+
+[tasks.config.json](../../../tasks.config.json) sets `"libraryModeCL": true`. That determines which npm scripts are legal:
+
+| Available in Library mode                                                                                          | **Not** available (Component mode only)                    |
+| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `createLib`, `switchLib`, `listLib`, `deleteLib`                                                                    | `publishAll`                                               |
+| `createLibVersion`, `switchLibVersion`, `deleteLibVersion`                                                          | `promoteWebPack`, `revertWebPack`                          |
+| `publishLibVersion`, `restoreLibVersion`, `storeLibVersion`                                                         | `exportRC`                                                 |
+| `listPublishedLib`, `deletePublishedLib`, `showStatus`, `setPermanent`                                              |                                                            |
+| `importLibVersion`, `exportLibVersion`, `move`, `startDevServer`                                                    |                                                            |
+
+`npm run publish` and `npm run publishLibVersion` both resolve to `custom-dx-components publish`. Never suggest a Component-mode command while `libraryModeCL` is `true` — it will fail.
+
+## Server configuration
+
+All connection settings live under `server-config` in [tasks.config.json](../../../tasks.config.json). Read it before advising anything — do not assume defaults.
+
+| Key                              | Meaning                                                                       |
+| -------------------------------- | ----------------------------------------------------------------------------- |
+| `server`                         | Infinity base URL, e.g. `https://localhost:1080/prweb`                        |
+| `serverType`                     | `infinity`                                                                     |
+| `authService`                    | Infinity authentication service alias — used when `grantType` is `authCode`   |
+| `grantType`                      | `authCode`, `passwordCreds`, or `clientCreds`                                 |
+| `clientId`                       | OAuth client registration ID                                                   |
+| `clientSecret`                   | Required **only** for `passwordCreds` and `clientCreds`                       |
+| `redirectUri`                    | OAuth redirect, e.g. `https://localhost:4010/`                                |
+| `cert` / `key`                   | SSL cert and key, needed when `grantType` is `authCode` and `redirectUri` is `https://localhost` |
+| `rulesetName` / `rulesetVersion` | Target ruleset for published components                                        |
+| `archiveRulesetName` / `archiveRulesetVersion` | Ruleset used by `exportLibVersion` / `importLibVersion`          |
+| `devBuild`, `devServerPort`      | Local dev server settings for `startDevServer`                                |
+| `questions_ask*`                 | Controls which settings `npm run authenticate` re-prompts for                 |
+
+### Secrets
+
+`clientSecret`, `user`, and `password` sit in a tracked file. **Never** write a real secret into [tasks.config.json](../../../tasks.config.json) on the user's behalf, never echo one into the terminal, and never paste one into a chat response. If a credential is needed, tell the user to enter it themselves at the `npm run authenticate` prompt.
+
+The [keys/](../../../keys) folder holds `dxcb.crt` and `dxcb.key` for the local HTTPS redirect listener. These are local development certificates — they are not deployment credentials and must not be reused as such.
+
+## Procedure
+
+### Authenticate
+
+```bash
+npm run authenticate
+```
+
+Run this first whenever the token may be stale, the server has changed, or a publish returns 401/403. It prompts only for the settings listed in `questions_askOnce` / `questions_askAlways` — currently `server,authService` are asked once.
+
+### Publish
+
+```bash
+npm run validate -- <Org>_<Library>_<Name> N N        # the component must build clean first
+npm run test
+npm run publish
+```
+
+Publish only when the user explicitly asks. Publishing writes to a shared Pega server and is not a local, reversible action.
+
+### Version lifecycle
+
+```bash
+npm run listLib               # what libraries exist locally
+npm run listPublishedLib      # what is already on the server
+npm run showStatus            # local vs published drift
+npm run createLibVersion      # start a new version
+npm run switchLibVersion      # move between versions
+npm run storeLibVersion       # snapshot the current version into store/
+npm run restoreLibVersion     # bring a stored version back
+npm run setPermanent          # lock a published version
+```
+
+`store/` and `<Org>_<Library>/` are **generated** folders — they do not exist until `storeLibVersion` and a build have run. Do not reference them as if they were checked in.
+
+### Versioning rules
+
+- `component.version` in [tasks.config.json](../../../tasks.config.json) seeds the `version` written into each new component's `config.json`.
+- `component.library` must equal the `library` value in every `config.json` and the `Pega_<library>_` name prefix. A mismatch fails the build.
+- Bump the version before publishing a change to an already-published library version, or use `createLibVersion` for a breaking change.
+- `setPermanent` makes a published version immutable — confirm with the user before running it.
+
+## Common Failures
+
+- **401 / 403 on publish** — token expired. Run `npm run authenticate`.
+- **Redirect never completes on `authCode`** — `cert` and `key` are missing or untrusted. Both are required when `redirectUri` starts with `https://localhost`.
+- **`clientSecret` empty with `passwordCreds` or `clientCreds`** — that grant type requires it; `authCode` does not.
+- **Command "not found" or silently wrong** — a Component-mode script was used while `libraryModeCL` is `true`. Check the table above.
+- **Library name mismatch** — `component.library`, the `library` key in `config.json`, and the `<Org>_<Library>_` folder prefix must all agree.
+
+## Before Publishing
+
+1. `npm run validate -- <Org>_<Library>_<Name> N N` (or `validateAll`) passes
+2. `npm run test` passes, coverage thresholds met
+3. `npm run lint` and `npm run _lint:spelling` pass
+4. Version bumped if the target version is already published
+5. The user has explicitly asked to publish

package/src/ai/project/.claude/skills/radiobuttons/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: radiobuttons
+description: 'Scaffold a Pega DX Field component with subtype **Radiobuttons** — single-select radio group bound to a case property. Use when: user asks for radio buttons, a mutually exclusive option group, a rating scale, a segmented choice, or an inline yes/no/maybe selector.'
+argument-hint: 'Describe the radio group (e.g., "a three-option priority selector shown inline")'
+---
+
+# Create Radiobuttons Field
+
+Field subtype `Radiobuttons`. Binds to a case property whose value is one key from a small option set.
+
+Read [../field/SKILL.md](../field/SKILL.md) for the shared Field rules first. This skill adds only what is specific to `Radiobuttons`.
+
+## Cosmos Mapping
+
+| Mode | Component |
+| --- | --- |
+| Edit | `RadioButtonGroup` from `@pega/cosmos-react-core` |
+| `DISPLAY_ONLY` | The **display label** for the stored key |
+
+## Picklist or Radiobuttons
+
+| Use radio buttons when | Use a picklist when |
+| --- | --- |
+| Two to roughly five options | More than five options |
+| All options should be visible at once | The list is long or data-page driven |
+| The choice is central to the form | The choice is secondary |
+
+## Value Handling
+
+- Store the **key**, render the **label**, exactly as with a picklist.
+- Dispatch with `changeNblur`.
+- Every option needs a stable `key`. Do not use the array index — reordering the options would silently remap stored data. Compare keys as strings (`` `${value}` === `${item.key}` ``) and give the group a `name` of `pageReference.propName` so two groups on different pages never share a name.
+- On blur call `validate(value)` only when there is no value, so a required group reports its error.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `orientation` | Orientation | `SELECT` | `"vertical"` | options: `vertical`, `horizontal` |
+| `options` | Options (comma separated) | `TEXT` |  |  |
+
+## Gotchas
+
+- `RadioButtonGroup` owns the group label and the accessible grouping. Do not wrap it in a separate `FieldGroup` label as well, or screen readers announce the name twice.
+- A radio group cannot be deselected by default. The platform's own group offers an opt-in clear (`allowClear` with `onClear` committing `''`) and an environment flag for click-to-deselect; if you need it, add it deliberately as an authoring option, or add an explicit "None" option. Do not assume an empty click clears the value.
+- Keep every option label short enough to read inline when `orientation` is `horizontal`.
+- Do not use radio buttons for a true boolean — use `boolean`.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.

package/src/ai/project/.claude/skills/review-component/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: review-component
+description: 'Independent, read-only audit of a finished Pega DX component (Field, Widget, Template or Presentation) against the project checklist. Use when: the user asks to review, audit, check or sign off a component; or before reporting a new component as done. Reports findings by severity with file and line evidence; it does not edit files.'
+argument-hint: 'The component key to review (for example Acme_Lib_Quantity), plus the brief if you have it'
+---
+
+# Review a DX Component
+
+A second pair of eyes for a component that is already built. The author checked their own work; this review exists to catch what they missed and what they claimed without proof. It is **read-only**: report findings, do not fix them. The author (or a separate step) fixes, then the check script is rerun.
+
+## When to run it
+
+- A new Field, Widget or Template is built and about to be reported done. Skip it for a one-line fix.
+- The user asks for a review, audit or quality check of an existing component.
+
+## Stay independent
+
+A reviewer that reads the author's conclusions tends to agree with them.
+
+- If your tool can start a sub-agent or a fresh session, delegate the review and give it only: the component key, the original brief (or the user's request), and this skill. **Do not pass the author's summary, test results or opinion of the code.**
+- If you must review in the same session, re-read every file from disk instead of relying on memory, and treat every claim in your own earlier report as unproven until you find the code or test that shows it.
+
+## Procedure
+
+1. **Locate the component** at `src/components/<Org>_<Library>_<Name>/` and note its type and subtype from `config.json`. If you were not given a brief, reconstruct the intended behavior from the user's request and `config.json`, and say that you did.
+2. **Get the mechanical facts first.** Run `node .claude/skills/validate-component/scripts/check-component.mjs <key> --no-build` and take its table as given. Do not repeat what it checks (schema, `tsc`, ESLint, Jest, properties read, scans). Spend your effort on what a script cannot judge. Note any `FAIL` row as a finding.
+3. **Read the files in this order:** `config.json`, `index.tsx` and any helper files, `styles.ts`, `mock.ts`, `demo.stories.tsx`, `demo.test.tsx`.
+4. **Walk the checklist** in [references/checklist.md](./references/checklist.md): the common section, the section for the component type, accessibility, and tests and stories. For every item decide pass, fail or not applicable. A fail needs evidence.
+5. **Use a saved plan if there is one** (for example `requirements/<Name>.plan.md`): its acceptance criteria and trace are the brief. Then **trace each requirement in the brief** to the code that implements it and the test that proves it. A requirement with no test is a finding. A test that does not assert the behavior it is named after is a finding.
+6. **Check the author's report, if there is one,** against the check table and the code. A claim with no support is a Blocker (checklist item R1).
+7. **Write the report** in the format below.
+
+## Rules for the reviewer
+
+- Every finding cites `file:line` and the checklist id. No evidence, no finding.
+- Say "cannot determine" instead of guessing, and list it under Not verified.
+- Do not invent platform behavior. Use the references this project ships; for a PCore or PConnect method, check the API catalog under `.claude/skills/references/`.
+- Report the real problems. Do not pad the report with style opinions the checklist does not mention, and do not repeat one root cause as several findings.
+- Do not edit, create or delete files. Do not run publish, authenticate or delete commands.
+
+## Report format
+
+1. **Verdict:** `Ready`, `Ready after minor fixes`, or `Not ready`, with one sentence of reasoning. `Not ready` if there is any Blocker or two or more Majors.
+2. **Findings**, most severe first. Each one: severity, checklist id, `file:line`, what is wrong, why it matters to a user or to saved data, and the smallest fix.
+   - **Blocker:** corrupts or loses data, a security problem, an accessibility barrier, a requirement not met, or a false claim in the report.
+   - **Major:** breaks a platform contract, a missing state, a missing guard, or a missing test for a stated requirement.
+   - **Minor:** convention or polish that does not change behavior.
+3. **Requirements trace:** each requirement, the code that implements it, the test that proves it, or `no test`.
+4. **Not verified:** what you could not check (for example the build, a real Pega server, a screen reader) and why.

package/src/ai/project/.claude/skills/review-component/references/checklist.md

@@ -0,0 +1,77 @@
+# Review Checklist
+
+Each item has an id, the check, and the severity if it fails. The right-hand column names the reference that explains the rule. Mark an item not applicable only when it truly does not apply, and say so.
+
+## Common (every component)
+
+| Id | Check | If it fails | Reference |
+| --- | --- | --- | --- |
+| C1 | Every requirement in the brief is implemented. | Blocker | the brief |
+| C2 | Every `config.json` property changes behavior. Its default in `config.json` matches the fallback in code, and numbers and booleans that arrive as strings are normalized. | Major | [config-schema.md](../../create-dx-component/references/config-schema.md) |
+| C3 | The UI is built from Cosmos components. Styled-components appear only for what Cosmos cannot express, and there are no inline styles. | Minor, Major if layout or text is hand-built | [AGENTS.md](../../../../AGENTS.md) |
+| C4 | No `dangerouslySetInnerHTML`. Any URL from data is checked against an allow-list of protocols before it is rendered as a link. No secrets or environment URLs. | Blocker | [field-behavior.md](../../create-dx-component/references/field-behavior.md) |
+| C5 | Imports are only React, Cosmos packages, styled-components and local files, unless the user approved a library. | Major | [AGENTS.md](../../../../AGENTS.md) |
+| C6 | The component is exported with `withConfiguration()` and imports `create-nonce`. | Major | [create-dx-component](../../create-dx-component/SKILL.md) |
+| C7 | Visible text goes through the localization service, not hard-coded literals, apart from scaffold placeholders. | Minor | [widget-patterns.md](../../create-dx-component/references/widget-patterns.md) |
+| C8 | Every PCore and PConnect method called appears in the API catalog. An undocumented one is justified to the user. | Major | [pcore-pconnect-apis.md](../../create-dx-component/references/pcore-pconnect-apis.md) |
+
+## Field
+
+| Id | Check | If it fails | Reference |
+| --- | --- | --- | --- |
+| F1 | Typing updates a local draft. The store is written on blur (or on change only for stepper and slider variants), not on every keystroke. | Major | [field-behavior.md](../../create-dx-component/references/field-behavior.md) |
+| F2 | A blur with an unchanged value does not commit but still validates. An unchanged empty value validates `''`. | Major | field-behavior.md |
+| F3 | Clearing sends `''`. Zero is a value: there is no `if (!value)` on a number. A `null` stored value is read as empty (`?? ''`). | Blocker if a clear or zero corrupts data | field-behavior.md |
+| F4 | Invalid input is never silently turned into another value (`''`, `0`) and committed. An out-of-range or malformed draft is not committed, and the user sees an error. | Blocker | field-behavior.md |
+| F5 | `DISPLAY_ONLY`, `readOnly`, `disabled` and `required` are handled, including string booleans. A read-only control cannot commit. | Major | [props-contract.md](../../create-dx-component/references/props-contract.md) |
+| F6 | `validatemessage` becomes an error status and replaces the helper text. `clearErrorMessages` runs on edit. Hiding the label keeps the helper text. | Minor | field-behavior.md |
+| F7 | The subtype traps in field-behavior.md are respected: date-only values are not time-zone shifted, a URL is checked against `http` and `https`, a phone number that is only a country code is empty, a picklist stores the key and shows the label. | Blocker or Major | field-behavior.md |
+
+## Widget
+
+| Id | Check | If it fails | Reference |
+| --- | --- | --- | --- |
+| W1 | The fetch effect resets loading and error at the start, ignores a response that arrives after unmount or a dependency change, and returns a cleanup. | Major | [widget-patterns.md](../../create-dx-component/references/widget-patterns.md) |
+| W2 | A failed load is an error state, never an empty list. "Nothing to show" and "could not load" are different messages. | Major | widget-patterns.md |
+| W3 | Object props are dependencies by a stable key, not by identity, and a change in any input refetches. | Major | widget-patterns.md |
+| W4 | Loading, empty, error, retry and refresh exist and use Cosmos state components. Refresh keeps the current rows visible. | Major | [state-matrix.md](../../create-dx-component/references/state-matrix.md) |
+| W5 | An async action cannot be activated twice, and its pending flag is reset when it fails. | Major | widget-patterns.md |
+| W6 | Every subscription uses a unique name, unsubscribes with the same name and context, and is not recreated on every render. | Major | widget-patterns.md |
+| W7 | A failed mutation shows a message. A destructive action asks for confirmation and does not run if confirmation is unavailable. Focus is restored after a delete. | Major | widget-patterns.md |
+| W8 | List keys are stable ids, not the array index. | Minor | widget-patterns.md |
+
+## Template
+
+| Id | Check | If it fails | Reference |
+| --- | --- | --- | --- |
+| T1 | `children` are treated as regions. Fields come from `getChildren()`, regions are found by name, and the element from `getComponent()` is memoized. | Major | [template-patterns.md](../../create-dx-component/references/template-patterns.md) |
+| T2 | A DETAILS template forces `readOnly` and `displayMode: 'DISPLAY_ONLY'` on its children. | Blocker for DETAILS | template-patterns.md |
+| T3 | `NumCols` and other numeric settings are parsed from strings with a fallback. | Major | template-patterns.md |
+| T4 | Hidden children leave no gap, and a region whose children are all hidden also drops its heading. | Minor | template-patterns.md |
+| T5 | Columns use `minmax(0, 1fr)` tracks. There is no fixed pixel width for text, no `100vh`, no landmark such as `main`, and no `document.title` change. | Minor | template-patterns.md |
+| T6 | Heading levels are sequential, and instructions appear only when a heading is shown. | Minor | template-patterns.md |
+
+## Accessibility
+
+| Id | Check | If it fails | Reference |
+| --- | --- | --- | --- |
+| A1 | Every control has an accessible name. Hiding the label keeps a name. Repeated controls have distinct names. | Major | [accessibility.md](../../create-dx-component/references/accessibility.md) |
+| A2 | An error is tied to its control and is not shown by color alone. | Major | accessibility.md |
+| A3 | Everything a pointer can do works from the keyboard, focus stays visible, and focus moves deliberately after an action, never on load. | Major | accessibility.md |
+| A4 | Loading finished, saved and failed are announced without taking focus. | Major | accessibility.md |
+| A5 | Text wraps, nothing needs a fixed width, and the layout works at narrow widths. | Minor | accessibility.md |
+
+## Tests and stories
+
+| Id | Check | If it fails | Reference |
+| --- | --- | --- | --- |
+| S1 | Each applicable state in the state matrix has a story and an assertion. | Major | [state-matrix.md](../../create-dx-component/references/state-matrix.md) |
+| S2 | Tests assert what a user sees and the arguments of commits. No `.skip` or `.only`, no deleted assertions, and no test that only checks the mock. | Major | [test-pattern.md](../../create-dx-component/references/test-pattern.md) |
+| S3 | Tests cover the edge cases: empty, `null`, zero, long values, and for widgets a late response and a failed request. | Major | test-pattern.md |
+| S4 | Mock data is deterministic and contains no production data or secrets. | Minor | test-pattern.md |
+
+## Report honesty
+
+| Id | Check | If it fails |
+| --- | --- | --- |
+| R1 | Every claim in the author's report (built, tested, verified, accessible) is supported by the check table or by code you read. A step shown as `NOT RUN` or `FAIL` is not reported as passing. | Blocker |

package/src/ai/project/.claude/skills/template/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: template
+description: 'Scaffold and implement a Pega DX **Template** component — a layout container that arranges child views/fields (FORM, DETAILS, PAGE subtypes). Use when: user wants a layout wrapper, a custom column/section arrangement, a container for child fields, or asks for a Template subtype.'
+argument-hint: 'Describe the layout (e.g., "a two-column form with a sidebar" or "a tabbed details template")'
+---
+
+# Create Template Component Skill
+
+## Prefer a Subtype Skill
+
+If the subtype is clear, use the narrower skill instead — it carries the layout rules this skill does not repeat.
+
+| Subtype | Skill |
+| --- | --- |
+| FORM | `form` |
+| DETAILS | `details` |
+| PAGE | `page` |
+
+Use this skill when the subtype is unclear, or the layout is unusual (tabs, steps, a sidebar): see [choosing-type-and-subtype.md](../create-dx-component/references/choosing-type-and-subtype.md).
+
+## When to Use
+
+- User wants a **layout container** that receives and arranges child components
+- User mentions a Template subtype: **FORM**, **DETAILS**, **PAGE**
+- User needs `CONTENTPICKER` in App Studio so authors can add child fields/views
+- Component takes a `children` array as its primary content
+
+Do NOT use this skill for components that own their own data (see `widget`), single-property bindings (see `field`), or read-only formatters (see `field`, which handles `DISPLAY_ONLY`).
+
+## Procedure
+
+The repo-wide rules (gallery reuse, contract approval and its layout, authoring properties, consent, Cosmos first, no dead code) are in `AGENTS.md` and are not repeated here.
+
+### Step 0: Check the UI Gallery
+
+Follow [ui-gallery-reuse.md](../create-dx-component/references/ui-gallery-reuse.md).
+
+### Step 1: Agree the contract
+
+Besides the name, label, description, library and version, the draft states:
+
+- **Subtype**: FORM, DETAILS or PAGE
+- **Layout primitive**: Cosmos `Grid`, `Flex`, `FieldGroup` or `Card` composition
+- **Regions**: the region names (`A`, `B`, `C`, or `Fields`), which are required, and how they stack when narrow
+- **Configurable knobs**: column count, gap, section headings, `showLabel`, orientation
+- **States to cover**: the applicable rows from [state-matrix.md](../create-dx-component/references/state-matrix.md)
+
+### Step 2: Scaffold
+
+`npm run create -- Template <FORM|DETAILS|PAGE> <Name> "<Label>" <version> <Library> "<description>" <Organization>`
+
+Pass every argument: a bare `npm run create` prompts interactively and hangs an agent. The CLI also accepts `FORM-region` and `DETAILS-region`. If no library exists yet, run `npm run createLib -- <Library> 1.0.0 Y Current` first. See [cli-workflow.md](../create-dx-component/references/cli-workflow.md).
+
+### Step 3: Implement
+
+Implement every scaffolded file from [template-essentials.md](../create-dx-component/references/template-essentials.md); open a deeper reference only when its closing table says so. Layout is where Cosmos coverage is best: never create styled-components for grids, flex rows, cards or gaps. Templates do not need `event-utils.ts`.
+
+### Step 4: Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` (`--no-build` while fixing), and paste the final table into your report. For a new component, run the `review-component` skill as described in [create-dx-component](../create-dx-component/SKILL.md). `npm run startStorybook` is long-running, so leave it to the user.

package/src/ai/project/.claude/skills/text/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: text
+description: 'Scaffold a Pega DX Field component with subtype **Text** — free-text single-line or multi-line input bound to a string case property. Use when: user asks for a text field, string input, notes/comment box, masked text, textarea, or a custom-formatted text display.'
+argument-hint: 'Describe the text field (e.g., "a single-line SSN input with a mask")'
+---
+
+# Create Text Field
+
+Field subtype `Text`. Binds to a string case property.
+
+Read [../field/SKILL.md](../field/SKILL.md) for the shared Field rules first. This skill adds only what is specific to `Text`.
+
+## Cosmos Mapping
+
+| Mode | Component |
+| --- | --- |
+| Edit, single line | `Input` from `@pega/cosmos-react-core` |
+| Edit, multi line | `TextArea` |
+| `DISPLAY_ONLY` | Raw `{value}` inside the styled wrapper |
+
+## Value Handling
+
+- `value` arrives as `string`. Default it to `''`, never `undefined`, or the input flips to uncontrolled.
+- `onChange` sends `event.target.value` straight through — no coercion.
+- Trim only on blur if the requirement calls for it, and send the trimmed value through `handleEvent(actions, 'blur', propName, trimmed)`.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `placeholder` | Placeholder | `TEXT` |  |  |
+| `maxLength` | Maximum length | `NUMBER` |  |  |
+| `multiLine` | Multi-line | `BOOLEAN` | `false` |  |
+
+## Gotchas
+
+- **`Input` does not render a character counter.** Passing `maxLength` only sets the native attribute. Only `TextArea` has `maxLength` + `displayCharCount`. For a counter on a single-line field, wrap a bare `Input` in your own `FormField` and set `charLimitDisplay`.
+- **`Input` renders its own `FormField` when `label` is passed.** If you compose it inside your own `FormField`, pass `label` to the outer one only, or you nest two. Give both the **same explicit `id`** so the label's `htmlFor` resolves.
+- **`FormField.onClear` only renders for radio/checkbox groups** (it is gated behind `isRadioCheck`). For a text input clear button, pass an `actions` array instead.
+- For masked input, mask on change and store the unmasked value in the case property unless the business rule says otherwise.
+- `TextArea` needs an explicit `rows` or it collapses to one line in some Constellation containers.
+
+## Validate
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` and paste its table into your final report.