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

package/src/ai/index.js

@@ -0,0 +1,154 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+// Everything the CLI ships for AI coding tools lives under src/ai and is copied into a project only when AI is enabled:
+//   project/           mirrors the project root (AGENTS.md, .gemini/, .claude/skills/<component skills>)
+//   catalog/           the PCore/PConnect skills, installed into .claude/skills next to the component skills
+//   readme-section.md  the README section describing the AI setup
+// The list of installed files is derived from these folders, so nothing needs to be registered twice.
+const AI_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_DIR = path.join(AI_DIR, 'project');
+const CATALOG_DIR = path.join(AI_DIR, 'catalog');
+const README_SECTION_FILE = path.join(AI_DIR, 'readme-section.md');
+
+// Claude Code, GitHub Copilot and Cursor discover project skills at .claude/skills/<name>/SKILL.md (one level deep).
+const SKILLS_TARGET = path.join('.claude', 'skills');
+
+// Codex CLI and Gemini CLI read .agents/skills rather than .claude/skills, so they get a link to the same folder
+// instead of a copy. Copilot and Cursor also scan .agents/skills and de-duplicate by skill name.
+const AGENTS_SKILLS_TARGET = path.join('.agents', 'skills');
+
+// The project's own format check (`prettier -c .`) would otherwise flag every installed AI file, because they are
+// formatted for this repository, not for the customer's Prettier settings. ESLint already ignores `.claude`.
+const PRETTIER_IGNORE_FILE = '.prettierignore';
+const PRETTIER_IGNORE_BLOCK = ['# ai-agents:start', '.claude/', '.agents/', '.gemini/', 'AGENTS.md', '# ai-agents:end'].join('\n');
+const PRETTIER_IGNORE_SECTION = /\n?# ai-agents:start[\s\S]*?# ai-agents:end\n?/;
+
+const README_AGENT_SECTION = /<!-- ai-agents:start -->[\s\S]*?<!-- ai-agents:end -->\n*/;
+const README_FOLLOWING_SECTION = '## Latest Documentation';
+
+const listFiles = (directory, relative = '') =>
+  fs.readdirSync(path.join(directory, relative), { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = path.join(relative, entry.name);
+    if (entry.isDirectory()) return listFiles(directory, entryPath);
+    return entry.name === '.DS_Store' ? [] : [entryPath];
+  });
+
+const exists = (target) => {
+  try {
+    fs.lstatSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// Project-relative paths of every file the CLI installs. .agents/skills is normally a link and is handled separately.
+const shippedFiles = () => [...listFiles(PROJECT_DIR), ...listFiles(CATALOG_DIR).map((file) => path.join(SKILLS_TARGET, file))];
+
+const linkAgentsSkills = async (projectDirectory) => {
+  const skillsDirectory = path.join(projectDirectory, SKILLS_TARGET);
+  const linkPath = path.join(projectDirectory, AGENTS_SKILLS_TARGET);
+
+  await fs.promises.mkdir(path.dirname(linkPath), { recursive: true });
+  await fs.promises.rm(linkPath, { recursive: true, force: true });
+  try {
+    // A junction needs no elevated rights on Windows; on other platforms the type is ignored.
+    await fs.promises.symlink(path.relative(path.dirname(linkPath), skillsDirectory), linkPath, 'junction');
+  } catch {
+    await fs.promises.cp(skillsDirectory, linkPath, { recursive: true });
+  }
+};
+
+const addReadmeSection = async (projectDirectory) => {
+  const readmePath = path.join(projectDirectory, 'README.md');
+  if (!fs.existsSync(readmePath)) return;
+
+  const readme = await fs.promises.readFile(readmePath, 'utf8');
+  if (README_AGENT_SECTION.test(readme)) return;
+
+  const section = (await fs.promises.readFile(README_SECTION_FILE, 'utf8')).trimEnd();
+  const insertAt = readme.indexOf(README_FOLLOWING_SECTION);
+  const updated = insertAt === -1 ? `${readme.trimEnd()}\n\n${section}\n` : `${readme.slice(0, insertAt)}${section}\n\n${readme.slice(insertAt)}`;
+  await fs.promises.writeFile(readmePath, updated);
+};
+
+const addPrettierIgnore = async (projectDirectory) => {
+  const ignorePath = path.join(projectDirectory, PRETTIER_IGNORE_FILE);
+  const current = exists(ignorePath) ? await fs.promises.readFile(ignorePath, 'utf8') : '';
+  if (PRETTIER_IGNORE_SECTION.test(current)) return;
+
+  const separator = current === '' || current.endsWith('\n') ? '' : '\n';
+  await fs.promises.writeFile(ignorePath, `${current}${separator}${PRETTIER_IGNORE_BLOCK}\n`);
+};
+
+// Removes only the block the CLI added, and the file itself when nothing else is in it.
+const removePrettierIgnore = async (projectDirectory) => {
+  const ignorePath = path.join(projectDirectory, PRETTIER_IGNORE_FILE);
+  if (!exists(ignorePath)) return;
+
+  const current = await fs.promises.readFile(ignorePath, 'utf8');
+  if (!PRETTIER_IGNORE_SECTION.test(current)) return;
+
+  const remaining = current.replace(PRETTIER_IGNORE_SECTION, '\n').replace(/^\n+/, '');
+  if (remaining.trim() === '') {
+    await fs.promises.rm(ignorePath);
+  } else {
+    await fs.promises.writeFile(ignorePath, remaining);
+  }
+};
+
+export const hasAgentFiles = (projectDirectory) => shippedFiles().some((file) => exists(path.join(projectDirectory, file)));
+
+// Existing files are never overwritten, so edits survive a re-enable.
+export const enableAgentFiles = async (projectDirectory) => {
+  await fs.promises.cp(PROJECT_DIR, projectDirectory, { recursive: true, force: false });
+  await fs.promises.cp(CATALOG_DIR, path.join(projectDirectory, SKILLS_TARGET), { recursive: true, force: false });
+  await linkAgentsSkills(projectDirectory);
+  await addReadmeSection(projectDirectory);
+  await addPrettierIgnore(projectDirectory);
+};
+
+// Only the files the CLI ships are removed, so anything a user added later (their own skills, .github/workflows,
+// .claude/settings.json) survives.
+export const removeAgentFiles = async (projectDirectory) => {
+  const agentsSkills = path.join(projectDirectory, AGENTS_SKILLS_TARGET);
+  const files = shippedFiles();
+
+  if (exists(agentsSkills)) {
+    if (fs.lstatSync(agentsSkills).isSymbolicLink()) {
+      // Removing the link must never remove the skills it points to.
+      await fs.promises.rm(agentsSkills);
+    } else {
+      // The link could not be created at install time and the skills were copied instead.
+      const skillFiles = files.filter((file) => file.startsWith(SKILLS_TARGET + path.sep)).map((file) => path.relative(SKILLS_TARGET, file));
+      files.push(...skillFiles.map((file) => path.join(AGENTS_SKILLS_TARGET, file)));
+    }
+  }
+
+  await Promise.all(files.map((file) => fs.promises.rm(path.join(projectDirectory, file), { force: true })));
+
+  // Prune folders left empty, deepest first.
+  const directories = new Set(['.agents']);
+  files.forEach((file) => {
+    for (let directory = path.dirname(file); directory !== '.'; directory = path.dirname(directory)) {
+      directories.add(directory);
+    }
+  });
+  const deepestFirst = [...directories].sort((a, b) => b.split(path.sep).length - a.split(path.sep).length);
+  for (const directory of deepestFirst) {
+    const target = path.join(projectDirectory, directory);
+    if (exists(target) && fs.readdirSync(target).length === 0) {
+      await fs.promises.rmdir(target);
+    }
+  }
+
+  const readmePath = path.join(projectDirectory, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    const readme = await fs.promises.readFile(readmePath, 'utf8');
+    await fs.promises.writeFile(readmePath, readme.replace(README_AGENT_SECTION, ''));
+  }
+
+  await removePrettierIgnore(projectDirectory);
+};

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

@@ -0,0 +1,43 @@
+---
+name: boolean
+description: 'Scaffold a Pega DX Field component with subtype **Boolean** — true/false input bound to a boolean case property. Use when: user asks for a checkbox, toggle, switch, yes/no field, consent or opt-in control, or a boolean display.'
+argument-hint: 'Describe the boolean field (e.g., "a consent checkbox that shows Yes/No when read-only")'
+---
+
+# Create Boolean Field
+
+Field subtype `Boolean`. Binds to a boolean case property.
+
+Read [../field/SKILL.md](../field/SKILL.md) for the shared Field rules first. This skill adds only what is specific to `Boolean`.
+
+## Cosmos Mapping
+
+| Mode | Component |
+| --- | --- |
+| Edit | `Checkbox` from `@pega/cosmos-react-core` |
+| `DISPLAY_ONLY` | `BooleanDisplay` |
+
+## Value Handling
+
+- `value` may arrive as a real boolean **or** the strings `'true'` / `'false'`. Normalize before render: checked only when `value === true || value === 'true'`.
+- A property that was never set arrives as `null`. A checkbox has no null state: show it unchecked and write `false` with `handleEvent(actions, 'change', propName, false, { skipDirtyValidation: true })` so the form is not marked dirty by a value the user never touched. If you offer a two-radio (true/false) variant, skip that write so "unset" stays distinct from "false".
+- `onChange` sends `event.target.checked`, not `event.target.value`.
+- Boolean fields use `changeNblur` — dispatch the change and the field-change in one step, since there is no meaningful blur for a checkbox: `handleEvent(actions, 'changeNblur', propName, event.target.checked)`.
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `trueLabel` | Label when true | `TEXT` | `"Yes"` |  |
+| `falseLabel` | Label when false | `TEXT` | `"No"` |  |
+
+## Gotchas
+
+- `Checkbox` renders its own label. Do not add a separate `Text` label beside it. Production uses two labels: the field `label` is the legend of a `CheckboxGroup`, and the checkbox's own `label` comes from a `caption` prop (default `@FL .$this.name`). It uses a bare `Checkbox` only when the label is hidden or empty. Add `caption` to `config.json` if you want that split, and put `info` and `status` on the group (or on the bare checkbox).
+- Custom true/false text (`trueLabel`, `falseLabel`) is read from raw config, strips a leading `@L`, and is localized with the localization service.
+- A required boolean means "must be checked". Validation must reject `false`, not just `undefined`.
+- `hideLabel` on a checkbox still needs an accessible name — keep the `label` prop populated and set `labelHidden`.
+
+## 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/case/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: case
+description: 'Scaffold a Pega DX Widget component with subtype **CASE** — a data-driven block rendered inside a case view, with access to the current case context. Use when: user asks for a case-scoped chart, KPI, related-records table, case timeline, attachment list, or any block that reads the current case ID.'
+argument-hint: 'Describe the case widget (e.g., "a table of related contacts for the current case")'
+---
+
+# Create CASE Widget
+
+Widget subtype `CASE`. Rendered **inside a case view** and has access to the current case.
+
+Read [../widget/SKILL.md](../widget/SKILL.md) for the shared Widget rules first. This skill adds only what is specific to `CASE`.
+
+## Defining Trait
+
+A CASE widget can read the case it is rendered in.
+
+Take the property name from `PCore.getConstants().CASE_INFO.CASE_INFO_ID` and read the ID with `pConn.getValue(thatProperty, '')`.
+
+If the block does **not** need the case, use `page-widget` instead — a CASE widget placed on a portal page has no case to read and will fetch with an empty key.
+
+## Reading the case
+
+`CaseInfo` has no status getter (check the typedefs before assuming a getter exists). Read case identity with `pConn.getCaseInfo()` (`getKey()`, `getID()`, ...) and case properties with `pConn.getValue(propertyPath, defaultValue)`. Confirm the property path in your application.
+
+## Data Fetch
+
+Pass the case key as the `CaseInstanceKey` data-view parameter (`{ dataViewParameters: { CaseInstanceKey: caseID } }`) to `PCore.getDataApiUtils().getData(dataPage, payload, context)`. Run it in a `useEffect` keyed on `[context, caseID, dataPage]`: reset loading and error first, ignore a response that arrives after unmount or a dependency change, and keep a failure distinct from an empty result. The guarded fetch shape is in [widget-patterns.md](../create-dx-component/references/widget-patterns.md).
+
+See [widget-patterns.md](../create-dx-component/references/widget-patterns.md) for cancellation, subscriptions (a case widget often refetches on a case push), mutations and the traps to avoid.
+
+## Required States
+
+| State | Cosmos component |
+| --- | --- |
+| Loading | `Progress` |
+| Empty | `EmptyState` |
+| Error | `ErrorState` (with `onRetry`) or `Banner` |
+| Data | `Table`, `Grid`, or a chart |
+
+## config.json Additions
+
+| Property | Label | Format | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `label` | Label value | `TEXT` |  |  |
+| `dataPage` | Data page | `TEXT` |  |  |
+| `maxRows` | Maximum rows | `NUMBER` | `10` |  |
+
+## Gotchas
+
+- Guard the empty case ID. On first render `caseID` may be `''`, and fetching with it returns unrelated rows or an error — skip the fetch until it is populated.
+- Include `caseID` in the effect dependency array, or the widget shows stale data after the user navigates to a different case.
+- Do not refetch on every parent re-render. A Constellation case view re-renders often.
+- Write-back to a case property must go through `updateFieldValue` plus `triggerFieldChange`, preserving the source's original shape.
+- The widget must not assume it is the only consumer of the data page — never mutate the response array in place.
+
+## 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/create-dx-component/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: create-dx-component
+description: 'General Pega DX component scaffolding — shared references, assets, and the router when the component type is UNCLEAR. Prefer the type-specific skills (`field`, `template`, `widget`, `presentation`) when the user names a type. Use THIS skill only when: the type is ambiguous, the user asks for general DX component guidance, or multiple types are being created together.'
+argument-hint: 'Describe the component you want (e.g., "a date range picker field" or "a KPI widget showing case metrics")'
+---
+
+# Create DX Component Skill (Router / Shared Reference)
+
+## Type-Specific Skills
+
+If the user's request clearly matches one component type, use the focused skill instead of this one:
+
+| User asks for… | Use skill |
+| --- | --- |
+| Input field, property-bound value, Text/Boolean/Date/Email/Phone/Currency/Picklist/Radiobuttons | [field](../field/SKILL.md) |
+| Layout container, FORM/DETAILS/PAGE arrangement, `children` wrapper | [template](../template/SKILL.md) |
+| Chart, KPI, table, dashboard tile, data-page-driven block, spin wheel, self-fetching UI | [widget](../widget/SKILL.md) |
+| Replace how the whole case view is rendered (`CASEVIEW` / `WSSCASEVIEW`) | [presentation](../presentation/SKILL.md) |
+| Plan a component from requirements, or port one from another design system or framework | [plan-dx-component](../plan-dx-component/SKILL.md) |
+| Change, fix or extend a component that **already exists** | [update-dx-component](../update-dx-component/SKILL.md) |
+
+A read-only badge, pill, icon or formatted value bound to a property is a `field` that handles `DISPLAY_ONLY`; one that shows its own data is a `widget`. For an unusual request (a custom control, a board, a layout with tabs, something that may not be a custom component at all), read [choosing-type-and-subtype.md](./references/choosing-type-and-subtype.md): it has the fit check and maps ideas onto the subtypes the CLI accepts.
+
+## Procedure
+
+The repo-wide rules (gallery reuse, contract approval and its layout, authoring properties, third-party consent, Cosmos first, no dead code) are in `AGENTS.md`, which is always loaded. They are not repeated here.
+
+### Step 0: Check the Constellation UI Gallery
+
+Follow [ui-gallery-reuse.md](./references/ui-gallery-reuse.md). On a match, use the gallery component's `config.json` as the starting proposal for Step 1.
+
+### Step 1: Agree the contract
+
+If the user supplied requirements, links, images or a named design system, read them first ([intake.md](../plan-dx-component/references/intake.md)); for a large or unclear input, plan first with [plan-dx-component](../plan-dx-component/SKILL.md). The draft covers:
+
+- **Type and subtype**: any subtype the CLI accepts ([cli-workflow.md](./references/cli-workflow.md)); for a Field, the one matching the stored value type. Say why.
+- **Name, label, description, library and version** (normally `1.0.0`; confirm rather than assume)
+- **Behavior, data and runtime contract**: what it renders, data pages, actions, editable and read-only expectations
+- **Authoring properties** with formats and defaults
+- **States to cover**, from [state-matrix.md](./references/state-matrix.md); each gets a story and a test assertion
+- **Third-party libraries**, each with its purpose and whether it is installed
+
+Do not scaffold or touch `config.json` until the user approves.
+
+### Step 2: Scaffold via CLI (non-interactive)
+
+If no library exists yet, run `npm run createLib -- <Library> 1.0.0 Y Current`. Then scaffold, **passing every argument**:
+
+`npm run create -- <type> <subtype> <Name> "<Label>" <version> <Library> "<description>" <Organization>`. For example, `npm run create -- Field Text-Email ContactEmail "Contact email" 1.0.0 Lib "Email field" Acme` creates `src/components/Acme_Lib_ContactEmail`.
+
+The scaffold creates `index.tsx`, `config.json`, `styles.ts`, `mock.ts`, `demo.stories.tsx`, `demo.test.tsx` (and `localizations.json` when the scaffold shows its own text), plus `PConnProps.d.ts` and `create-nonce.ts` once in `src/components/shared/`. **It is a working sample, not an empty skeleton**: replace everything that does not serve the request, including the story, mock, test and localization strings. Delete a generated shared helper your component does not use. If anything goes wrong, see [cli-workflow.md](./references/cli-workflow.md).
+
+### Step 3: Implement
+
+Read the essentials file for the type and implement every scaffolded file from it: [field-essentials.md](./references/field-essentials.md), [widget-essentials.md](./references/widget-essentials.md), [template-essentials.md](./references/template-essentials.md) or [presentation-essentials.md](./references/presentation-essentials.md). Each one ends with a table of when to open a deeper reference; open those only when the situation applies.
+
+Before writing a `PCore` or `pConn` call, search the catalog for the method name as described in [pcore-pconnect-apis.md](./references/pcore-pconnect-apis.md), and follow the matching `pconnect-*` skill for call order and pitfalls.
+
+### Step 4: Run the check loop
+
+Run `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>` from the project root. It runs the schema check, `tsc`, ESLint, Jest, the config-to-props sync check, the story and test coverage warnings, the inline-style, raw-HTML and secret scans, and the build. While fixing failures, add `--no-build`; run it once without the flag at the end.
+
+Fix every FAIL before reporting the work as done, and **paste the final table into your report**. Do not weaken a check to make it pass. A `NOT RUN` row is not a pass: say so and give the reason.
+
+### Step 5: Independent review (new components)
+
+For a new Field, Widget or Template, run the [review-component](../review-component/SKILL.md) skill before reporting it done, ideally in a fresh sub-agent that sees the brief but not your summary. Fix every Blocker and Major it reports, rerun the check script, and include the verdict in the final report. Skip this step for a small edit to an existing component.
+
+### Step 6: Review in Storybook (user)
+
+`npm run startStorybook` starts a long-running dev server. Leave it to the user unless they ask.
+
+## Verify the Cosmos API before you use it
+
+Cosmos prop names are often not what they sound like, and several plausible component names do not exist. Before importing a component or passing a prop you have not used in this repo before, read `node_modules/@pega/cosmos-react-core/lib/components/<Name>/<Name>.d.ts` and confirm the export in `node_modules/@pega/cosmos-react-core/lib/index.d.ts`. Do not rely on training knowledge of the Cosmos API. Known traps are under Verified Gotchas in [cosmos-components.md](./references/cosmos-components.md); add any new one you find.
+
+## References and Cookbooks (open when needed)
+
+| File | What it gives you |
+| --- | --- |
+| [field-essentials.md](./references/field-essentials.md), [widget-essentials.md](./references/widget-essentials.md), [template-essentials.md](./references/template-essentials.md), [presentation-essentials.md](./references/presentation-essentials.md) | The must-follow rules for each type, file by file. Read the one for your type first |
+| [ui-gallery-reuse.md](./references/ui-gallery-reuse.md) | Checking the Constellation UI Gallery and adapting a match |
+| [cli-workflow.md](./references/cli-workflow.md) | Project layout, non-interactive CLI commands, naming rules, the check loop, troubleshooting |
+| [props-contract.md](./references/props-contract.md) | The props each type receives; reading and writing values; display modes |
+| [component-patterns.md](./references/component-patterns.md) | Code skeletons for each component type |
+| [config-schema.md](./references/config-schema.md) | `config.json` structure, formats, `defaultConfig` bindings, what `validate-schema` checks |
+| [storybook-pattern.md](./references/storybook-pattern.md), [test-pattern.md](./references/test-pattern.md) | Story, mock and Jest conventions |
+| [template-patterns.md](./references/template-patterns.md) | Template regions and children, forcing read-only, responsive columns, field groups, tabs, PAGE |
+| [widget-patterns.md](./references/widget-patterns.md) | Widget fetch lifecycle, cancellation, duplicate-click guards, subscriptions, mutations, confirm-before-delete |
+| [field-subtypes-extra.md](./references/field-subtypes-extra.md) | Text-Input, Text-Paragraph, Icon-Button-URL, DateTime, TimeOfDay, Picklist-Autocomplete |
+| [field-behavior.md](./references/field-behavior.md) | Field commit protocol, null/zero/empty, message precedence, dates and time zones, numbers, pickers |
+| [localization.md](./references/localization.md) | `localizations.json`, getLocalizedText, placeholders, plurals, formatting |
+| [accessibility.md](./references/accessibility.md) | What Cosmos covers and what the author owns; focus, headings, announcements; verification |
+| [choosing-type-and-subtype.md](./references/choosing-type-and-subtype.md) | The fit check and how to pick a type and subtype for an unusual request |
+| [state-matrix.md](./references/state-matrix.md) | The states to cover per component type |
+| [cosmos-components.md](./references/cosmos-components.md) | Which Cosmos component to use, and verified gotchas |
+| [pcore-pconnect-apis.md](./references/pcore-pconnect-apis.md) | How to look up a PCore/PConnect method |
+| [cookbooks/](./cookbooks/README.md) | End-to-end recipes: a field with limits and validation; a data widget with loading, empty and error states |

package/src/ai/project/.claude/skills/create-dx-component/assets/PConnProps.d.ts

@@ -0,0 +1,24 @@
+import { PConnect } from '@pega/pcore-pconnect-typedefs';
+
+export interface PConnProps {
+  getPConnect: () => typeof PConnect;
+}
+
+export interface PConnFieldProps extends PConnProps {
+  label: string;
+  required: boolean;
+  disabled: boolean;
+  value: any;
+  validatemessage: string;
+  status?: string;
+  onChange?: any;
+  onBlur?: any;
+  readOnly: boolean;
+  testId: string;
+  helperText: string;
+  displayMode?: string;
+  hideLabel: boolean;
+  placeholder?: string;
+  fieldMetadata?: any;
+  additionalProps?: any;
+}

package/src/ai/project/.claude/skills/create-dx-component/assets/create-nonce.ts

@@ -0,0 +1,5 @@
+// @ts-ignore
+if (window?.__webpack_nonce__) {
+  // @ts-ignore
+  __webpack_nonce__ = window.__webpack_nonce__;
+}

package/src/ai/project/.claude/skills/create-dx-component/assets/event-utils.ts

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

package/src/ai/project/.claude/skills/create-dx-component/assets/styles.ts

@@ -0,0 +1,7 @@
+import styled, { css } from 'styled-components';
+
+export default styled.div(() => {
+  return css`
+    margin: 0px 0;
+  `;
+});

package/src/ai/project/.claude/skills/create-dx-component/cookbooks/README.md

@@ -0,0 +1,28 @@
+---
+title: Component Authoring Cookbook — Recipe Index
+description: End-to-end recipes for building and customizing Constellation DX components (fields, widgets, templates), indexed by symptom/keyword and primary method for AI/RAG retrieval.
+---
+
+# Cookbook: Component Authoring
+
+> Part of the [create-dx-component skill](../SKILL.md).
+
+Every file in [`../references/`](../references/) documents one topic at a time. Each file in this folder walks through **one complete component change** from scaffold to a passing build: which command to run, which files to edit, the code, the story and the tests. The code in each recipe was run in a generated project (`tsc`, Jest, schema validation, lint and bundle all passed).
+
+Each recipe is a single, self-contained file with:
+
+- YAML frontmatter (`keywords`, `primary_methods`, `related`) for structured/metadata search.
+- A **Problem** statement in plain language.
+- A **Solution** with numbered steps and the exact code.
+- A **Discussion** with the rules and pitfalls behind the code.
+- **Related recipes**.
+
+## Recipe Index
+
+| Recipe                                                                                   | Use it when                                                                                       | Primary methods                                                              |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [Customize a field with limits, a counter and validation messages](./field-with-limits-and-validation.md) | Changing how a field edits or validates a value; adding configurable properties to a field       | `updateFieldValue`, `triggerFieldChange`, `getStateProps`                    |
+| [Build a data-driven widget with loading, empty and error states](./build-a-data-widget.md) | Showing data from a data page in a panel or table; any component that loads data asynchronously  | `getDataApiUtils().getData`, `getContextName`, `getLocalizedText`            |
+| [Show a property as a colored status badge](./status-badge-field.md) | A read-only value, pill or badge bound to a property; handling `DISPLAY_ONLY`; a configurable value-to-color map | `getStateProps`, Cosmos `Status` |
+
+For recipes on the **runtime APIs** a component calls (submitting assignments, validation, subscriptions, collaboration), use the cookbooks of the `pconnect-*` skills linked from the [skills index](../../README.md).