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

package/src/ai/project/.claude/skills/create-dx-component/cookbooks/build-a-data-widget.md

@@ -0,0 +1,281 @@
+---
+title: Build a data-driven widget with loading, empty and error states
+keywords: [widget, data page, getDataApiUtils, getData, loading state, empty state, error state, retry, localization, useEffect]
+primary_methods: [DataApiUtils.getData, PConnect.getContextName, LocalizationService.getLocalizedText]
+related: [field-with-limits-and-validation]
+---
+
+# Recipe: Build a data-driven widget with loading, empty and error states
+
+> Part of the [Component Authoring cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A page needs a panel that lists rows from a data page (for example the operator's open work). The data page and the number of rows must be configurable. The panel must show a loading indicator, an empty message when there is nothing to show, and an error with a retry button when the request fails.
+
+## Solution
+
+**1. Scaffold a page widget** (run `npm run createLib -- Lib 1.0.0 Y Current` first in a new project):
+
+```bash
+npm run create -- Widget PAGE WorkPanel "Work panel" 1.0.0 Lib "Panel listing open work" Acme
+```
+
+**2. Replace `properties` in `config.json`** so a designer can choose the title, data page and row count:
+
+```json
+"properties": [
+  { "name": "title", "label": "Title", "format": "TEXT", "defaultValue": "Work list" },
+  { "name": "dataPage", "label": "Data page", "format": "TEXT", "defaultValue": "D_pyMyWorkList" },
+  { "name": "pageSize", "label": "Rows to show", "format": "NUMBER", "defaultValue": 10 },
+  {
+    "label": "Conditions",
+    "format": "GROUP",
+    "properties": [{ "name": "visibility", "label": "Visibility", "format": "VISIBILITY" }]
+  }
+]
+```
+
+**3. Write `index.tsx`:**
+
+```tsx
+import { useCallback, useEffect, useState } from 'react';
+import { withConfiguration, Table, EmptyState, ErrorState } from '@pega/cosmos-react-core';
+import type { PConnFieldProps } from '../shared/PConnProps';
+import '../shared/create-nonce';
+
+import StyledAcmeLibWorkPanelWrapper from './styles';
+
+interface AcmeLibWorkPanelProps extends PConnFieldProps {
+  title?: string;
+  dataPage?: string;
+  pageSize?: number | string;
+}
+
+interface WorkRow {
+  id: number;
+  caseType: string;
+  status: string;
+  stage: string;
+}
+
+type LoadState = 'loading' | 'ready' | 'error';
+
+function AcmeLibWorkPanel(props: AcmeLibWorkPanelProps) {
+  const { getPConnect, title = 'Work list', dataPage = 'D_pyMyWorkList', pageSize = 10 } = props;
+  const pConn = getPConnect();
+  const context = pConn.getContextName();
+  const localize = (text: string) => pConn.getLocalizationService().getLocalizedText(text);
+
+  const [rows, setRows] = useState<WorkRow[]>([]);
+  const [state, setState] = useState<LoadState>('loading');
+  const [attempt, setAttempt] = useState(0);
+  const size = Number.parseInt(String(pageSize), 10) || 10;
+
+  useEffect(() => {
+    let cancelled = false;
+    setState('loading');
+
+    PCore.getDataApiUtils()
+      .getData(dataPage, { paging: { pageNumber: 1, pageSize: size } }, context)
+      .then((response: any) => {
+        if (cancelled) return;
+        const data: any[] = response?.data?.data ?? [];
+        setRows(
+          data.map((entry, index) => ({
+            id: index,
+            caseType: entry.pxProcessName,
+            status: entry.pyAssignmentStatus,
+            stage: entry.pxTaskLabel
+          }))
+        );
+        setState('ready');
+      })
+      .catch(() => {
+        if (cancelled) return;
+        setRows([]);
+        setState('error');
+      });
+
+    // ignore a response that arrives after the component unmounted or the inputs changed
+    return () => {
+      cancelled = true;
+    };
+  }, [context, dataPage, size, attempt]);
+
+  const retry = useCallback(() => setAttempt((count) => count + 1), []);
+
+  if (state === 'error') {
+    return (
+      <StyledAcmeLibWorkPanelWrapper>
+        <ErrorState message={localize('Unable to load work')} onRetry={retry} />
+      </StyledAcmeLibWorkPanelWrapper>
+    );
+  }
+
+  if (state === 'ready' && rows.length === 0) {
+    return (
+      <StyledAcmeLibWorkPanelWrapper>
+        <EmptyState message={localize('No work found')} />
+      </StyledAcmeLibWorkPanelWrapper>
+    );
+  }
+
+  const columns: { renderer: keyof WorkRow; label: string }[] = [
+    { renderer: 'caseType', label: localize('Case type') },
+    { renderer: 'status', label: localize('Status') },
+    { renderer: 'stage', label: localize('Stage') }
+  ];
+
+  return (
+    <StyledAcmeLibWorkPanelWrapper>
+      <Table
+        title={localize(title)}
+        columns={columns}
+        data={rows}
+        loading={state === 'loading'}
+        loadingMessage={localize('Loading work')}
+      />
+    </StyledAcmeLibWorkPanelWrapper>
+  );
+}
+
+export default withConfiguration(AcmeLibWorkPanel);
+```
+
+**4. Add every user-visible string to `localizations.json`** under `fields`:
+
+```json
+{
+  "fields": {
+    "Case type": "Case type",
+    "Status": "Status",
+    "Stage": "Stage",
+    "Work list": "Work list",
+    "Loading work": "Loading work",
+    "No work found": "No work found",
+    "Unable to load work": "Unable to load work"
+  }
+}
+```
+
+**5. Replace `mock.ts`, `demo.stories.tsx` and `demo.test.tsx`.** The story fakes only `PCore.getDataApiUtils().getData` and the two `pConn` methods the widget calls. Three stories drive the three states:
+
+```ts
+// mock.ts
+export const configProps = { title: 'Open work', dataPage: 'D_pyMyWorkList', pageSize: 10 };
+
+export const workListData = {
+  data: {
+    data: [
+      { pxProcessName: 'Loan request', pyAssignmentStatus: 'Open', pxTaskLabel: 'Review' },
+      { pxProcessName: 'Service request', pyAssignmentStatus: 'Pending', pxTaskLabel: 'Approve' }
+    ]
+  }
+};
+```
+
+```tsx
+// demo.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+
+import AcmeLibWorkPanel from './index';
+import { configProps, workListData } from './mock';
+
+const meta: Meta<typeof AcmeLibWorkPanel> = {
+  title: 'AcmeLibWorkPanel',
+  component: AcmeLibWorkPanel,
+  excludeStories: /.*Data$/
+};
+
+export default meta;
+type Story = StoryObj<typeof AcmeLibWorkPanel>;
+
+// Fake only the PCore function the component calls.
+const mockGetData = (getData: () => Promise<unknown>) => {
+  (globalThis as unknown as { PCore: unknown }).PCore = { getDataApiUtils: () => ({ getData }) };
+};
+
+const getPConnect = () =>
+  ({
+    getContextName: () => 'app/primary_1',
+    getLocalizationService: () => ({ getLocalizedText: (text: string) => text })
+  }) as any;
+
+const renderPanel = (getData: () => Promise<unknown>) => {
+  const Render: Story = (args: any) => {
+    mockGetData(getData);
+    return <AcmeLibWorkPanel getPConnect={getPConnect} {...args} />;
+  };
+  Render.args = { ...configProps };
+  return Render;
+};
+
+export const BaseAcmeLibWorkPanel = renderPanel(() => Promise.resolve(workListData));
+export const EmptyAcmeLibWorkPanel = renderPanel(() => Promise.resolve({ data: { data: null } }));
+export const ErrorAcmeLibWorkPanel = renderPanel(() => Promise.reject(new Error('Network error')));
+```
+
+```tsx
+// demo.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { composeStories } from '@storybook/react';
+import '@testing-library/jest-dom';
+
+import * as DemoStories from './demo.stories';
+import { workListData } from './mock';
+
+const { BaseAcmeLibWorkPanel, EmptyAcmeLibWorkPanel, ErrorAcmeLibWorkPanel } = composeStories(DemoStories);
+
+test('shows the loading message, then the rows', async () => {
+  render(<BaseAcmeLibWorkPanel />);
+  expect(screen.getByText('Loading work')).toBeVisible();
+
+  expect(await screen.findByText('Loan request')).toBeVisible();
+  expect(screen.getByText('Service request')).toBeVisible();
+  expect(screen.getByText('Case type')).toBeVisible();
+  expect(screen.queryByText('Loading work')).toBeNull();
+});
+
+test('shows the empty state when the data page returns no rows', async () => {
+  render(<EmptyAcmeLibWorkPanel />);
+  expect(await screen.findByText('No work found')).toBeVisible();
+});
+
+test('shows an error and recovers when the user retries', async () => {
+  render(<ErrorAcmeLibWorkPanel />);
+  expect(await screen.findByText('Unable to load work')).toBeVisible();
+
+  // the next request succeeds
+  (globalThis as unknown as { PCore: { getDataApiUtils: () => unknown } }).PCore.getDataApiUtils = () => ({
+    getData: () => Promise.resolve(workListData)
+  });
+  fireEvent.click(screen.getByRole('button', { name: /try again/i }));
+
+  expect(await screen.findByText('Loan request')).toBeVisible();
+});
+```
+
+**6. Run the check loop** from [cli-workflow.md](../references/cli-workflow.md):
+
+```bash
+npx jest src/components/Acme_Lib_WorkPanel --coverage=false
+npx tsc --noEmit 2>&1 | grep -v "demo.stories.tsx"
+npm run validate-schema -- Acme_Lib_WorkPanel
+npm run buildComponent -- Acme_Lib_WorkPanel N N
+```
+
+## Discussion
+
+- **MUST** handle all four outcomes of the request: pending, rows, no rows (`response.data.data` is `null` or empty) and failure. A widget that handles only the success path shows an empty table forever when the call fails.
+- **MUST** guard against a stale response. The `cancelled` flag in the effect cleanup stops a late response from updating state after the component unmounts or `dataPage`/`context` change.
+- Keep the effect dependencies to the inputs that should trigger a reload (`context`, `dataPage`, the page size and a retry counter). Putting `pConn` or a freshly created object in the dependency list reloads on every render. See [performance-and-efficiency.md](../../best-practices/performance-and-efficiency.md).
+- `getData(dataViewName, payload?, context?, options?)` is documented in [pcore-rest-data-details.md](../../references/pcore-rest-data-details.md). `getContextName()` is in [pconnect-reference-context-component.md](../../references/pconnect-reference-context-component.md) and `getLocalizedText` in [pconnect-case-info-data-info-localization.md](../../references/pconnect-case-info-data-info-localization.md).
+- `ErrorState` renders its retry button with the design system's own text ("Try again"). Query it by role and name in tests.
+- In the story, assign `PCore` through `globalThis` instead of `window.PCore = ...`. The `globals.d.ts` in the project declares `PCore` as a global constant, so the scaffolded `window.PCore` assignments produce `tsc` errors.
+- If the widget must call a REST endpoint instead of a data page, see [pcore-rest-data-details.md](../../references/pcore-rest-data-details.md) and the [error handling guide](../../best-practices/error-handling-and-resiliency.md).
+
+## Related recipes
+
+- [Customize a field with limits, a counter and validation messages](./field-with-limits-and-validation.md)
+- [Subscribe to data page changes](../../pconnect-data-subscriptions/SKILL.md)

package/src/ai/project/.claude/skills/create-dx-component/cookbooks/field-with-limits-and-validation.md

@@ -0,0 +1,156 @@
+---
+title: Customize a field with limits, a counter and validation messages
+keywords: [field, text input, updateFieldValue, triggerFieldChange, validatemessage, max length, uppercase, config.json property]
+primary_methods: [ActionsApi.updateFieldValue, ActionsApi.triggerFieldChange, PConnect.getStateProps]
+related: [build-a-data-widget]
+---
+
+# Recipe: Customize a field with limits, a counter and validation messages
+
+> Part of the [Component Authoring cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A text field must limit how many characters can be typed, optionally convert input to uppercase, show a `n/limit` counter, and show the platform's validation message. The limit and the uppercase option must be configurable by the designer.
+
+## Solution
+
+Run every command from the project root. Replace `Acme` and `Lib` with the project's organization and library.
+
+**1. Scaffold the field** (library mode needs `npm run createLib -- Lib 1.0.0 Y Current` once first; see [cli-workflow.md](../references/cli-workflow.md)):
+
+```bash
+npm run create -- Field Text CountedText "Counted text" 1.0.0 Lib "Text field with a character counter" Acme
+```
+
+**2. Add the designer-facing properties** to `src/components/Acme_Lib_CountedText/config.json`, next to `placeholder`:
+
+```json
+{ "name": "maxLength", "label": "Maximum characters", "format": "NUMBER", "defaultValue": 50 },
+{ "name": "forceUppercase", "label": "Convert to uppercase", "format": "BOOLEAN", "defaultValue": false }
+```
+
+**3. Read the properties in `index.tsx`.** Declare them in the props interface, give them defaults, and normalize them because they can arrive as strings:
+
+```tsx
+interface AcmeLibCountedTextProps extends PConnFieldProps {
+  // ...scaffolded props (isTableFormatter, formatter, variant)
+  maxLength?: number | string;
+  forceUppercase?: boolean | string;
+}
+
+const { /* ...scaffolded props */ validatemessage, maxLength = 50, forceUppercase = false } = props;
+
+const limit = Number.parseInt(String(maxLength), 10) || 50;
+const upper = forceUppercase === true || forceUppercase === 'true';
+const normalize = (raw: string) => (upper ? raw.toUpperCase() : raw).slice(0, limit);
+```
+
+**4. Write the value through the actions API.** `updateFieldValue` on every change, `triggerFieldChange` on blur:
+
+```tsx
+const handleOnChange = (event: any) => {
+  actions.updateFieldValue(propName, normalize(event.target.value));
+};
+
+const handleOnBlur = (event: any) => {
+  actions.triggerFieldChange(propName, normalize(event.target.value));
+};
+```
+
+`propName` is `pConn.getStateProps().value` (for example `.TextSample`), as in the scaffold. Leave the scaffolded `DISPLAY_ONLY` branch untouched so the field still works in details views and tables.
+
+**5. Render the counter and the validation message** on the editable `Input`:
+
+```tsx
+<Input
+  type='text'
+  value={value}
+  label={label}
+  labelHidden={hideLabel}
+  placeholder={placeholder}
+  disabled={disabled}
+  readOnly={readOnly}
+  required={required}
+  onChange={handleOnChange}
+  onBlur={handleOnBlur}
+  status={validatemessage ? 'error' : undefined}
+  info={validatemessage || `${(value ?? '').length}/${limit}`}
+  testId={testId}
+/>
+```
+
+**6. Extend the story and tests.** In `demo.stories.tsx`, forward the blur call to a story-only arg so a test can observe it:
+
+```tsx
+triggerFieldChange: (propName: string, theValue: any) => {
+  args.onTriggerFieldChange?.(propName, theValue);
+}
+```
+
+Replace the scaffolded test in `demo.test.tsx`:
+
+```tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { composeStories } from '@storybook/react';
+import '@testing-library/jest-dom';
+
+import * as DemoStories from './demo.stories';
+
+const { BaseAcmeLibCountedText } = composeStories(DemoStories);
+
+const getInput = () => screen.getByTestId('Text-12345678:input:control') as HTMLInputElement;
+
+test('shows the character counter', async () => {
+  render(<BaseAcmeLibCountedText maxLength={10} />);
+  expect(await screen.findByText('0/10')).toBeVisible();
+});
+
+test('truncates to the limit, converts to uppercase and commits on blur', async () => {
+  const onTriggerFieldChange = jest.fn();
+  // story-only arg: read by the story's fake getActionsApi, not a prop of the component
+  const storyArgs: Record<string, unknown> = { onTriggerFieldChange };
+  render(<BaseAcmeLibCountedText maxLength={5} forceUppercase {...storyArgs} />);
+
+  fireEvent.change(getInput(), { target: { value: 'hello world' } });
+  expect(getInput().value).toBe('HELLO');
+  expect(await screen.findByText('5/5')).toBeVisible();
+
+  fireEvent.blur(getInput());
+  expect(onTriggerFieldChange).toHaveBeenCalledWith('.TextSample', 'HELLO');
+});
+
+test('shows the validation message instead of the counter', async () => {
+  render(<BaseAcmeLibCountedText validatemessage='Value is required' />);
+  expect(await screen.findByText('Value is required')).toBeVisible();
+});
+
+test('renders only the value in DISPLAY_ONLY mode', async () => {
+  render(<BaseAcmeLibCountedText displayMode='DISPLAY_ONLY' value='Shown' />);
+  expect(await screen.findByText('Shown')).toBeVisible();
+  expect(screen.queryByTestId('Text-12345678:input:control')).toBeNull();
+});
+```
+
+**7. Run the check loop** from [cli-workflow.md](../references/cli-workflow.md):
+
+```bash
+npx jest src/components/Acme_Lib_CountedText --coverage=false
+npx tsc --noEmit 2>&1 | grep -v "demo.stories.tsx"
+npm run validate-schema -- Acme_Lib_CountedText
+npm run buildComponent -- Acme_Lib_CountedText N N
+```
+
+## Discussion
+
+- **MUST** keep the two-step write: `updateFieldValue` while typing so the store and the screen stay in sync, and `triggerFieldChange` on blur so validation and dependent fields run once the user is done. Calling only `triggerFieldChange` on every keystroke causes extra server round trips; calling only `updateFieldValue` never commits the change. Signatures: [pconnect-actions-api.md](../../references/pconnect-actions-api.md).
+- **MUST** normalize the value the same way in both handlers, otherwise the committed value can differ from what the user sees.
+- Declare a property in `config.json` **and** in the props interface, and give it a default. A designer can leave it empty and `maxLength` would otherwise be `undefined`.
+- Keep the read-only display branches. A field that only renders an input looks broken in details views ([props-contract.md](../references/props-contract.md)).
+- Use `fireEvent` from `@testing-library/react` in tests; the template does not install `@testing-library/user-event`.
+- Passing `onTriggerFieldChange` through a `Record<string, unknown>` spread keeps `tsc` clean without adding a test-only prop to the component.
+
+## Related recipes
+
+- [Build a data-driven widget with loading, empty and error states](./build-a-data-widget.md)
+- [Form and field validation APIs](../../pconnect-forms-and-fields/SKILL.md)

package/src/ai/project/.claude/skills/create-dx-component/cookbooks/status-badge-field.md

@@ -0,0 +1,97 @@
+---
+title: Show a property as a colored status badge (display-only Field)
+keywords: [status, badge, pill, display-only, DISPLAY_ONLY, Status, variant, Field, Text, statusMap, read-only value]
+primary_methods: [getStateProps, Status]
+related: [field-with-limits-and-validation, build-a-data-widget]
+---
+
+# Recipe: Show a property as a colored status badge
+
+> Part of the [Component Authoring cookbook](./README.md) — [skill overview](../SKILL.md).
+
+## Problem
+
+A case property holds a short status such as `Approved` or `Rejected`. In a details view or a table the user wants to see it as a colored badge, and the app designer should choose which value gets which color in App Studio. The same Field should still work as a normal text input when the view is editable.
+
+## Solution
+
+A read-only badge bound to a property is a **Field** (subtype `Text`) that handles `DISPLAY_ONLY`; it is not a Presentation component, and it is a Widget only if it loads its own data. See [choosing-type-and-subtype.md](../references/choosing-type-and-subtype.md).
+
+**1. Scaffold a Text field:**
+
+`npm run create -- Field Text StatusBadge "Status badge" 1.0.0 Lib "Shows a status as a colored badge" Acme`
+
+**2. Add one authoring property to `config.json`**, after the existing ones. The designer types value and color pairs:
+
+| Property | Label | Format | Notes |
+| --- | --- | --- | --- |
+| `statusMap` | Status colors | `TEXT` | helper text: "Value=color pairs, comma separated. Colors: success, urgent, warn, pending, info." |
+
+**3. Edit `index.tsx`.** Import `Status` from `@pega/cosmos-react-core` and add `statusMap?: string` to the props interface. Add two small, exported pure functions above the component:
+
+```typescript
+type StatusVariant = 'success' | 'urgent' | 'warn' | 'pending' | 'info';
+const STATUS_VARIANTS: StatusVariant[] = ['success', 'urgent', 'warn', 'pending', 'info'];
+
+// "Approved=success, Rejected=urgent" -> { approved: 'success', rejected: 'urgent' }
+export const parseStatusMap = (text = ''): Record<string, StatusVariant> =>
+  text.split(',').reduce<Record<string, StatusVariant>>((map, pair) => {
+    const [key, variant] = pair.split('=').map(part => part.trim());
+    if (key && STATUS_VARIANTS.includes(variant as StatusVariant)) map[key.toLowerCase()] = variant as StatusVariant;
+    return map;
+  }, {});
+
+// An unmapped or misspelled value gets the neutral 'info' variant instead of failing.
+export const variantFor = (value: string, statusMap?: string): StatusVariant =>
+  parseStatusMap(statusMap)[String(value).trim().toLowerCase()] ?? 'info';
+```
+
+Then replace only the `DISPLAY_ONLY` branch's value rendering, keeping the scaffold's empty placeholder:
+
+```typescript
+let displayComp: any = value ? (
+  <Status variant={variantFor(value, statusMap)}>{value}</Status>
+) : (
+  <span aria-hidden='true'>&ndash;&ndash;</span>
+);
+```
+
+Leave the editable `Input` as the scaffold has it. Remove the unused `variant?: any` from the props interface, because the dead-code rule and ESLint reject it.
+
+**4. Add tests** to `demo.test.tsx`. The pure functions are the part worth testing precisely:
+
+```typescript
+test('maps values to variants, ignoring case and bad entries', () => {
+  const map = 'Approved=success, Rejected = urgent, Bad=purple, =warn, Pending=pending';
+  expect(variantFor('approved', map)).toBe('success');
+  expect(variantFor(' Rejected ', map)).toBe('urgent');
+  expect(variantFor('Pending', map)).toBe('pending');
+});
+
+test('falls back to info for an unmapped value, a bad variant or no map', () => {
+  expect(variantFor('Unknown', 'Approved=success')).toBe('info');
+  expect(variantFor('Bad', 'Bad=purple')).toBe('info');
+  expect(variantFor('Approved')).toBe('info');
+});
+```
+
+Add a test that renders the component with `displayMode: 'DISPLAY_ONLY'` and a mapped value and checks the text is shown, and another with an empty value that checks the placeholder dash. Render the component directly with a small `getPConnect` that returns `getStateProps` and `getActionsApi`; see [test-pattern.md](../references/test-pattern.md).
+
+**5. Add a display-only story** in `demo.stories.tsx` (value `Approved`, `statusMap` set, `displayMode: 'DISPLAY_ONLY'`) so the badge can be reviewed in Storybook. The check script warns when there is only one story.
+
+**6. Run** `node .claude/skills/validate-component/scripts/check-component.mjs Acme_Lib_StatusBadge`.
+
+This recipe was built in a generated project: the schema check, `tsc`, ESLint and Jest all passed (the build step was not run there).
+
+## Discussion
+
+- **Why a map property and not hard-coded colors.** Statuses differ between applications. Putting the pairs in `config.json` lets the designer change them without a code change, and an unmapped value still renders, as the neutral `info` badge.
+- **`Status` takes five variants only**: `success`, `urgent`, `warn`, `pending` and `info`. The label is a string or number, and Cosmos transforms it to uppercase. Check the installed `Status.d.ts` before using another prop.
+- **Color is never the only signal.** The badge text carries the status, so a user who cannot distinguish the colors still reads it.
+- **Localization.** The badge shows the stored value as it is. If the values need translating, pass the text through `getLocalizedText` and add each possible value to `localizations.json`; see [localization.md](../references/localization.md).
+- **Editable mode** is the unchanged scaffold. If users must also edit the status, make it a picklist instead (see the `picklist` skill) so the value cannot be mistyped.
+
+## Related recipes
+
+- [Customize a field with limits, a counter and validation messages](./field-with-limits-and-validation.md)
+- [Build a data-driven widget](./build-a-data-widget.md)

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

@@ -0,0 +1,71 @@
+# Accessibility
+
+Accessibility is part of the component contract, not a final polish step. Cosmos components already carry most of the semantics (labels, roles, ARIA state, focus rings, keyboard behavior), which is the main reason to build from them (see the Cosmos-first rule in [AGENTS.md](../../../../AGENTS.md)). This file lists what the component author is still responsible for, and how to verify it with the tools the project already has.
+
+Target: WCAG 2.2 AA.
+
+## What Cosmos gives you, and what it does not
+
+| Cosmos provides | You must still provide |
+| --- | --- |
+| Label association, `required`, `aria-invalid` and error text on its inputs | A meaningful `label`, kept even when `hideLabel` is set (hide it visually, do not remove it) |
+| Roles, `aria-selected`, roving focus and arrow keys for `Tabs`; `inert` on inactive panels | Unique, stable tab ids; a sensible active tab when one disappears |
+| `role='alert'` on urgent and warning `Banner`, polite for the rest | Choosing the right variant, and an array for `messages` |
+| `fieldset` and `legend` for a named `FieldGroup`, `aria-expanded` on collapsible groups | Heading levels that stay sequential (see below) |
+| Visible `:focus-visible` rings | Not removing them in `styles.ts`, and deciding where focus goes after an action |
+| A busy indicator in `Progress` | A status message screen readers can hear: the `Progress` in the build checked does not announce by itself |
+
+## Rules
+
+1. **Semantic first.** Use the native element or the Cosmos component, then ARIA only to fill a real gap. Do not put `role` on something a Cosmos component already renders with that role.
+2. **Every control has an accessible name** that is stable and specific. Icon-only buttons need a `label` or `aria-label`. When several controls repeat (a row of Delete buttons), give each a distinct name (the item name in the label, or `contextualLabel` on a `SummaryList` item).
+3. **Associate help and errors with the control.** Pass `helperText` and `validatemessage` to the Cosmos control (as `info`) instead of rendering a separate paragraph. A validation message replaces helper text.
+4. **Never convey state by color alone.** Required, error, warning and success need text or an icon as well. Cosmos `status` does this for inputs.
+5. **Keyboard parity.** Everything a pointer can do, the keyboard can do, in a logical tab order. Hover-only information (a tooltip, a preview) needs a focus or key equivalent. Do not trap focus, except inside a modal, which Cosmos handles.
+6. **Announce asynchronous change without moving focus.** Loading finished, save succeeded, validation failed and a list changed should be announced through a polite live region or a `Banner`. Do not steal focus for a status message. Use `aria-busy` on a region that is refreshing in place.
+7. **Move focus deliberately, and only when the user acted.**
+   - After a destructive action on a list item, focus the next item or the Add button (`SummaryList` / `ViewAll` do this when given `deletedItemId` and `fallbackFocusRef`).
+   - After a refresh replaces the control that was activated, restore focus to a control that still exists (save `document.activeElement` first).
+   - After an error the user must fix, focus the first invalid control or the error summary (`Banner` accepts a `handle` with `focus()`).
+   - Do not move focus on load, on a timer, or when a background request finishes.
+8. **Headings.** The page template owns the `h1`. A top-level section is `h2`, nested sections `h3` and below, with no skipped levels. Use `Text variant` or `headingTag`, not a styled `span`. A `FieldGroup` title is a `legend`, not a heading, unless you pass `headingTag`.
+9. **Do not add landmarks** (`main`, `nav`) in a field, widget or template. The shell owns them.
+10. **Hidden means gone.** Remove hidden content (`display: none`, `inert`, or not rendering it), do not just move it off-screen or make it transparent, so it leaves the tab order and the reading order.
+11. **Reflow and zoom.** Content must work at 320 CSS pixels wide and at 200% zoom without two-dimensional scrolling. Use `minmax(0, 1fr)` grid tracks, wrapping text, and container-based breakpoints. Do not use fixed pixel widths for text containers.
+12. **Motion.** Respect `prefers-reduced-motion` for any animation you add in `styles.ts`. Cosmos handles its own.
+13. **Target size.** Interactive targets are at least 24 by 24 CSS pixels. Use Cosmos `Button` and `Link` rather than a bare clickable `span`.
+14. **Localization.** Labels, status text and error messages go through the localization service, and the layout must tolerate text that is 30 to 40 percent longer.
+15. **Reading order equals visual order.** In a multi-column template, the DOM order must match the order a sighted user reads; when columns stack, the semantic order must survive.
+
+## By component type
+
+- **Field:** the label, `required`, `disabled`, `readOnly` and error state must each be observable by role and name. A radio group has a group name. A masked or formatted input exposes the formatted value, not the raw one. The display-only form still needs a label (visible or associated). Clearing an error on edit must not silently remove the information the user needs.
+- **Widget:** a distinct, announced state for loading, empty, error, success and pending action. A list is a list (`ul`/`ol` or a Cosmos list component), a data table is a `Table` with headers. A chart needs a text alternative or a table with the same data. A control that changes the content below it says so.
+- **Template:** one `h1` only in a page template, sequential headings, `fieldset`/`legend` for groups of fields, `EmptyState` for an empty region, and a collapse order that keeps the reading order.
+
+## Verification
+
+Do these in the Jest test and in Storybook; an automated pass never replaces a keyboard check.
+
+**In `demo.test.tsx`** (only `fireEvent` and Testing Library are installed; do not rely on `user-event`):
+
+- Find controls by role and accessible name: `screen.getByRole('textbox', { name: /email/i })`, `getByRole('group', { name: 'Contact' })`, `getByRole('alert')`. A query that needs a test id because there is no role or name is an accessibility finding.
+- Assert state attributes: `toBeRequired()`, `toBeDisabled()`, `toHaveAttribute('aria-invalid', 'true')`, `toHaveAttribute('aria-busy', 'true')`, `toBeVisible()`.
+- Assert the error is exposed: after setting `validatemessage`, the message text is in the document and the control is described by it (`toHaveAccessibleDescription` where the installed jest-dom has it).
+- Keyboard path: `control.focus()`, `expect(control).toHaveFocus()`, `fireEvent.keyDown(control, { key: 'Enter' })` or `'ArrowDown'`, and assert the result. Test the Escape and Enter paths of any popover or modal you add.
+- Focus after an action: delete an item, then `expect(addButton).toHaveFocus()`; close a modal, then the trigger has focus.
+- Status announcement: `expect(await screen.findByRole('status')).toHaveTextContent(...)` or the `Banner` text, for loading finished, saved and failed.
+
+**Automated rule checking** with `jest-axe` is optional and is **not installed** in the project template. Adding it is a new dependency, so ask the user first (AGENTS.md, Third-Party Library Consent) with the library name (`jest-axe`), why (it catches missing names, invalid ARIA and contrast-independent rule violations that role queries miss), and that it would be a new dev dependency. Do not add it without approval.
+
+**By hand, in Storybook** (`npm run startStorybook` is user-run):
+
+1. Tab through the component without a mouse: order, visible focus, no trap, every action reachable.
+2. Operate every action with Enter and Space, and every list or tab group with the arrow keys.
+3. Zoom to 200% and narrow the viewport to 320px; nothing is clipped or needs horizontal scrolling.
+4. Turn on a screen reader (VoiceOver on macOS) and check the name, role, state and announcement for the default, error, loading and empty states.
+5. Check the error, required and read-only states without relying on color.
+
+## Reporting
+
+In the final report, say which of these were done and which were not. Never claim an accessibility pass from the automated tests alone.