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

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

@@ -0,0 +1,262 @@
+# Storybook Pattern
+
+## Standard Storybook File (demo.stories.tsx)
+
+```typescript
+/* eslint-disable react/jsx-no-useless-fragment */
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { configProps, stateProps } from './mock';
+import AcmeLibComponentName from './index';
+
+const meta: Meta<typeof AcmeLibComponentName> = {
+  title: 'AcmeLibComponentName',
+  component: AcmeLibComponentName,
+  excludeStories: /.*Data$/
+};
+
+export default meta;
+type Story = StoryObj<typeof AcmeLibComponentName>;
+
+export const BaseAcmeLibComponentName: Story = (args: any) => {
+  const [value, setValue] = useState(configProps.value);
+
+  const props = {
+    value,
+    additionalProps: configProps.additionalProps || {},
+    getPConnect: () => {
+      return {
+        getStateProps: () => {
+          return stateProps;
+        },
+        getActionsApi: () => {
+          return {
+            updateFieldValue: (propName: string, theValue: any) => {
+              setValue(theValue);
+            },
+            triggerFieldChange: () => { /* nothing */ }
+          };
+        },
+        getValidationApi: () => {
+          return {
+            validate: () => { /* nothing */ }
+          };
+        },
+        getInheritedProps: () => {
+          return {};
+        },
+        getContextName: () => {
+          return 'app/primary_1';
+        },
+        getLocalizationService: () => {
+          return {
+            getLocalizedText: (val: any) => val
+          };
+        },
+        getValue: (val: any) => val,
+        ignoreSuggestion: () => { /* nothing */ },
+        acceptSuggestion: () => { /* nothing */ },
+        setInheritedProps: () => { /* nothing */ },
+        resolveConfigProps: () => { /* nothing */ }
+      };
+    }
+  };
+
+  return (
+    <>
+      <AcmeLibComponentName {...props} {...args} />
+    </>
+  );
+};
+
+BaseAcmeLibComponentName.args = {
+  label: configProps.label,
+  helperText: configProps.helperText,
+  testId: configProps.testId,
+  readOnly: configProps.readOnly,
+  disabled: configProps.disabled,
+  required: configProps.required,
+  hideLabel: configProps.hideLabel,
+  displayMode: configProps.displayMode,
+  validatemessage: configProps.validatemessage
+};
+```
+
+## Controls (argTypes)
+
+Give the story meta `argTypes` so the Storybook controls panel is usable. Every authoring property in `config.json` (except platform-handled formats such as `VISIBILITY`, and `GROUP` wrappers) gets an entry; `check-component.mjs` warns about any that are missing.
+
+| `config.json` format | `argTypes` entry |
+| --- | --- |
+| `TEXT` | `{ control: 'text' }` |
+| `BOOLEAN` | `{ control: 'boolean' }` |
+| `NUMBER` | `{ control: { type: 'number', min, max, step } }`, copying `min` and `max` from `config.json` |
+| `SELECT` | `{ options: [keys], control: { type: 'select', labels: { key: 'value' } } }`, built from `source` |
+| `DATASOURCE`, objects, `getPConnect` | `{ table: { disable: true } }` |
+
+- A prop with a fixed set of values (`mode`, `wheelType`, `variant`) gets a `select` control with `options` and human-readable `labels`, never a free-text box.
+- Seed the base story's `args` from `mock.ts` `configProps`, whose values match the `config.json` defaults, so the panel opens on the authored defaults.
+- List the component's own props first, then common DX props such as `testId` and `hideLabel`.
+- Set explicit defaults in the story `args` for common DX props (`hideLabel: false`, `testId: ''`) and expose `hideLabel` as one boolean control.
+- Hide what cannot be edited in the panel (`getPConnect`, object props such as `datasource`) with `table: { disable: true }`.
+
+```typescript
+const meta: Meta<typeof AcmeLibMyWidget> = {
+  title: 'AcmeLibMyWidget',
+  component: AcmeLibMyWidget,
+  excludeStories: /.*Data$/,
+  argTypes: {
+    mode: {
+      options: ['game', 'business'],
+      control: { type: 'select', labels: { game: 'Game (place bets)', business: 'Business (pick an item)' } }
+    },
+    hideLabel: { control: 'boolean' },
+    getPConnect: { table: { disable: true } }
+  }
+};
+```
+
+## Widget Storybook Pattern (with PCore mocking)
+
+For widgets that use `PCore` global APIs:
+
+```typescript
+/* eslint-disable react/jsx-no-useless-fragment */
+import type { Meta, StoryObj } from '@storybook/react';
+import AcmeLibMyWidget from './index';
+import mockData from './mock';
+
+const meta: Meta<typeof AcmeLibMyWidget> = {
+  title: 'AcmeLibMyWidget',
+  component: AcmeLibMyWidget,
+  excludeStories: /.*Data$/
+};
+
+export default meta;
+type Story = StoryObj<typeof AcmeLibMyWidget>;
+
+if (!window.PCore) {
+  window.PCore = {} as any;
+}
+
+export const BaseAcmeLibMyWidget: Story = (args: any) => {
+  window.PCore.getConstants = () => {
+    return { CASE_INFO: { CASE_INFO_ID: 'caseInfo.ID' } } as any;
+  };
+
+  window.PCore.getLocaleUtils = () => {
+    return { getLocaleValue: (value: any) => value } as any;
+  };
+
+  window.PCore.getDataApiUtils = () => {
+    return {
+      getData: () => new Promise(resolve => resolve(mockData))
+    } as any;
+  };
+
+  const props = {
+    getPConnect: () => {
+      return {
+        getValue: (value: any) => value,
+        getContextName: () => 'app/primary_1',
+        getLocalizationService: () => ({
+          getLocalizedText: (value: any) => value
+        }),
+        getActionsApi: () => ({
+          updateFieldValue: () => {},
+          triggerFieldChange: () => {}
+        }),
+        ignoreSuggestion: () => {},
+        acceptSuggestion: () => {},
+        setInheritedProps: () => {},
+        resolveConfigProps: () => {}
+      };
+    }
+  };
+
+  return (
+    <>
+      <AcmeLibMyWidget {...props} {...args} />
+    </>
+  );
+};
+
+BaseAcmeLibMyWidget.args = {
+  label: 'Widget Title'
+};
+```
+
+## Template Storybook Pattern
+
+For templates with children:
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import AcmeLibMyTemplate from './index';
+import { configProps } from './mock';
+
+const meta: Meta<typeof AcmeLibMyTemplate> = {
+  title: 'AcmeLibMyTemplate',
+  component: AcmeLibMyTemplate,
+  excludeStories: /.*Data$/
+};
+
+export default meta;
+type Story = StoryObj<typeof AcmeLibMyTemplate>;
+
+export const BaseAcmeLibMyTemplate: Story = (args: any) => {
+  const props = {
+    ...configProps,
+    children: [
+      <div key="1">Child 1</div>,
+      <div key="2">Child 2</div>
+    ],
+    getPConnect: () => ({
+      getInheritedProps: () => ({}),
+      getActionsApi: () => ({
+        updateFieldValue: () => {},
+        triggerFieldChange: () => {}
+      }),
+      getValidationApi: () => ({ validate: () => {} })
+    })
+  };
+
+  return <AcmeLibMyTemplate {...props} {...args} />;
+};
+
+BaseAcmeLibMyTemplate.args = {
+  label: 'Template Label',
+  showLabel: true,
+  NumCols: '2'
+};
+```
+
+## `mock.ts` rules
+
+
+Export the sample props the story needs, at minimum `configProps` and, for components bound to a property, `stateProps` (scaffolds often export more, such as sample data or metadata):
+
+```typescript
+export const configProps = {
+  label: 'Spin Wheel',
+  names: 'Alice, Bob, Carol, Dan, Eve',
+  spinDuration: 800
+};
+
+export const stateProps = {
+  value: '.Names'
+};
+```
+
+- `configProps` keys mirror `config.json` property names, with fully resolved values — never the `@L` prefix.
+- `stateProps.value` is the dot-notation case property path the component binds to.
+- Widget fixtures must be realistic enough that the story renders without a live Pega server.
+
+## Story conventions
+
+
+- Name the base story `Base<InnerFunctionName>` — `demo.test.tsx` imports it by that name through `composeStories`.
+- If the return is wrapped in a fragment, start the file with `/* eslint-disable react/jsx-no-useless-fragment */`.
+- Empty mock callbacks need a `/* nothing */` comment body to satisfy lint.
+- Story and mock files are excluded from the main ESLint config, but keep them consistent with the rest of the repo anyway.

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

@@ -0,0 +1,54 @@
+# Styles Pattern (`styles.ts`)
+
+> Part of the [create-dx-component skill](../SKILL.md).
+
+## Required shape
+
+
+```typescript
+import styled, { css } from 'styled-components';
+
+export default styled.div(() => {
+  return css`
+    margin: 0px 0;
+  `;
+});
+```
+
+- Default-export a single `styled.div`.
+- Import both `styled` and `css`.
+- Consume it in `index.tsx` as `StyledWrapper` wrapping the component's return value.
+
+## Styled-components are a LAST RESORT
+
+
+The canonical rule lives in [AGENTS.md](../../../../AGENTS.md). What it means *in this file* — the concrete allow and deny lists:
+
+Legitimate uses:
+
+- keyframe animations, `transform`, `transition`
+- hover/focus/drag states Cosmos does not expose
+- SVG and canvas styling
+- a positional override Cosmos props cannot express
+
+Never write rules here for:
+
+- layout — use `Flex` or `Grid`
+- cards and panels — use `Card`, `CardHeader`, `CardContent`
+- typography, sizing, or colour of text — use `Text` variants
+- badges and pills — use `Status`, `Tag`, `Count`
+- loading and empty states — use `Progress`, `EmptyState`
+
+## Other rules
+
+
+- Never use inline `style={{ ... }}` in `index.tsx`. All custom CSS belongs here.
+- Target children by class name from inside the wrapper; do not export additional styled components unless `index.tsx` imports each one.
+- Every rule must apply to an element that actually renders. Delete selectors for markup that no longer exists — dead CSS is dead code.
+- Prefer Cosmos design tokens over hardcoded colours and spacing.
+
+## The theme is not available here
+
+`@pega/cosmos-react-core` bundles its own nested copy of `styled-components`, so `theme.base` is `undefined` in this file and `theme.base.palette` throws. Read the theme in `index.tsx` with `useTheme()` and pass the values in as transient props (`$error`, `$success`). The worked example is in [cosmos-components.md](./cosmos-components.md#styled-components-theme-does-not-cross-the-boundary).
+
+Valid `base.palette` keys include `primary-background`, `secondary-background`, `foreground-color`, `app-background`, `brand-primary`, `urgent`, `warn`, `success`, `pending`, `info`, `interactive`, `border-line`. Props-driven styled components are also the right home for state-driven `transform`, `transition` and animation values, which keeps them out of inline styles.

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

@@ -0,0 +1,87 @@
+# Template essentials
+
+Read this instead of the deep references for a typical template. Open a deep reference only for the cases listed at the end.
+
+## Before you code
+
+- States to cover (mark one not applicable with a reason): all regions populated, optional region empty, required region empty, one child unavailable, long child content, narrow width, wide width, all children of a region hidden, read-only parent, nested template, missing or string config (`NumCols`). Add "active tab hidden or removed" for tabs.
+- Each covered state gets a `mock.ts` fixture, a story and at least one test assertion.
+- Start from the scaffolded files; the scaffold is a working sample, replace demo content that does not serve the request. Delete scaffold helpers you do not use.
+
+## index.tsx
+
+- `interface Props extends PConnFieldProps` with `children: any[]` and optional props named exactly like the `config.json` properties (`NumCols`, `showLabel`, ...). Export `withConfiguration(AcmeLibMyTemplate)`; keep `import '../shared/create-nonce';`. `PCore` is a global; do not import it.
+- `children` is one element per region, not per field. Normalize with `[props.children].flat(Infinity).filter(isValidElement)` and guard an empty value.
+- Find a region by `region.props.getPConnect().getRawMetadata().name` (`A`, `B`, `C`, `Fields`), not by index; if `find` returns `undefined`, fall back to `children[0]`. Never rename scaffold regions.
+- Editable layout: render `children` straight into a Cosmos `Grid`. Read-only or per-field layout: go one level down with `region.props.getPConnect().getChildren()`, render each with `getPConnect().getComponent()` in `useMemo`, and read labels with `resolveConfigProps(getConfigProps())`.
+- Merge inherited props over your own: `{ label, showLabel, ...getPConnect().getInheritedProps() }`; inherited wins.
+- Show the label when `showLabel` is true, or unset and editable; in display mode unless `showLabel === false`. No label, no heading.
+- `NumCols` is a string: `parseInt(NumCols, 10) || 1`; `Grid` `gap` is a Cosmos spacing unit (for example `2`), not pixels. Normalize flags with `true | 'true'`; guard numbers with `Number.isFinite`.
+- Branch on both `readOnly` and `displayMode === 'DISPLAY_ONLY'` (and `mode === 'editable'` on embedded data views). A DETAILS or read-only template forces each region child during render, with the same values every time:
+
+```typescript
+child.props.getPConnect().setInheritedProp('readOnly', true);
+child.props.getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY');
+```
+
+- Columns: `Grid` with `container={{ cols: 'repeat(N, minmax(0, 1fr))', gap }}`; column count and gap come from `config.json`, never hard-coded pixels. Block children (text areas, groups, tables) span the row. Wrap by container width, not viewport; prefer `Grid` responsive props or `useBreakpoint`.
+- Do not wrap children in extra `div`s, set `100vh`, or add landmarks. Reading order matches visual order.
+- Hidden children: hide the whole cell; when all children of a region or view are hidden, its heading disappears too. Show `EmptyState` when every region is empty.
+- Render the elements the platform created; do not add your own error boundary around them.
+- Use `FieldGroup` (with `name`) only when there is a label; show instructions only with a heading. Headings stay sequential: section `h2`, nested `h3`.
+- Tabs: Cosmos `Tabs` and `TabPanel`; do not reimplement them. Keep tab ids unique and stable; fall back to the first visible tab.
+- No secrets, tokens or per-environment URLs anywhere in the component folder (`check-component.mjs` fails).
+- Never mutate `getRawMetadata()` objects; clone first. Call hooks before any early return. Key children by `getRawMetadata().config.value` or `.name`, never a random id.
+- Localize labels with `PCore.getLocaleUtils().getLocaleValue(label, undefined, localeReference)`; `getLocalizedValue` is deprecated.
+- Cosmos-first, without deep imports from `lib/components/...`; check any new Cosmos prop in its `.d.ts` in `node_modules`. Look up every `PCore` and `pConn` call in [pcore-pconnect-apis.md](./pcore-pconnect-apis.md); use only documented methods.
+- No inline `style={{ ... }}`, `dangerouslySetInnerHTML`, `console`, nested ternaries, `++` or dead code.
+
+## config.json
+
+- Start from the scaffolded file, never from memory. Keep `type: "Template"`, the scaffolded `subtype`, the region `CONTENTPICKER` entries and `{ "format": "INSTRUCTIONS" }`.
+- Region and layout names are PascalCase or a single letter (`NumCols`, `Fields`, `A`); renaming one breaks saved views.
+- `NumCols` is a `SELECT` with keys `'1'`, `'2'`, `'3'` and a `defaultValue`. Set the `showLabel` default in `defaultConfig`.
+- Add only properties the user confirmed; `index.tsx` reads every named one, or `check-component.mjs` fails (`CONTENTPICKER`, `INSTRUCTIONS`, `VISIBILITY` and similar are platform-handled).
+- `validate-schema` rejects missing required keys, a wrong subtype, a property lacking `name`, `label` or `format`, and duplicates. It does not check `format`: use only scaffold formats. `SELECT` needs `source: [{ key, value }]`; `GROUP` has no `name`. Labels are sentence case without `@L`.
+
+## styles.ts
+
+- Keep the single default-exported `styled.div` wrapper.
+- Rules only for what Cosmos cannot express; never grid, flex, card or gap rules.
+- The theme is undefined here: `useTheme()` in `index.tsx`, pass values as transient props.
+- Hide a grid item rather than relying on margins; delete selectors for markup that is gone.
+
+## mock.ts and demo.stories.tsx
+
+- `mock.ts` exports `configProps` (`label`, `showLabel`, `NumCols`, resolved values, never `@L`).
+- Stories pass a `children` array and a fake `getPConnect` with exactly the methods the template calls (`getInheritedProps`, ...). For region or read-only behavior, fake children whose `getPConnect` provides `getRawMetadata`, `getChildren` and `setInheritedProp`.
+- Base story is `Base<InnerFunctionName>`; one story per covered state.
+- Meta `argTypes` gives every `config.json` property a matching control ([storybook-pattern.md](./storybook-pattern.md#controls-argtypes)); hide `getPConnect`.
+
+## demo.test.tsx
+
+- Query by role and accessible name (`getByRole('group', { name: 'Contact' })`); needing a test id is an accessibility finding. Use `fireEvent` (no `user-event`).
+- One assertion per covered state: all regions populated; an empty optional region; all children hidden hides the heading; read-only calls `setInheritedProp` with both `readOnly` and `displayMode`; column count from config, including `'2'` and a missing value; region found by name when the order differs.
+- Toggle props with `rerender`; never weaken an assertion.
+
+## localizations.json
+
+- A template that shows its own text lists every string under `fields` as `"English text": "English text"`, in step with the code.
+- Use whole sentences with `{0}` placeholders; plurals are separate keys; do not translate data or cache translated text.
+
+## Open a deep reference only when
+
+| Situation | Read |
+| --- | --- |
+| Container-width columns, nested templates, label alignment, field groups, tabs, PAGE layouts, hidden-child re-render | [template-patterns.md](./template-patterns.md) |
+| A FORM, DETAILS or PAGE specific rule | [form](../../form/SKILL.md), [details](../../details/SKILL.md), [page](../../page/SKILL.md) |
+| A config format beyond the scaffold's, visibility, bindings | [config-schema.md](./config-schema.md) |
+| A failing test, jsdom stubs, a fuller story fake | [test-pattern.md](./test-pattern.md), [storybook-pattern.md](./storybook-pattern.md) |
+| A Cosmos component you have not used, theme palette keys | [cosmos-components.md](./cosmos-components.md), [styles-pattern.md](./styles-pattern.md) |
+| Headings, focus, reflow, manual checks | [accessibility.md](./accessibility.md) |
+| Placeholders, plurals, formatting | [localization.md](./localization.md) |
+| Full prop list or skeleton | [props-contract.md](./props-contract.md), [component-patterns.md](./component-patterns.md) |
+| The full state list | [state-matrix.md](./state-matrix.md) |
+| An unusual layout | [choosing-type-and-subtype.md](./choosing-type-and-subtype.md) |
+
+Finish with `node .claude/skills/validate-component/scripts/check-component.mjs <Org>_<Library>_<Name>`; see [cli-workflow.md](./cli-workflow.md).

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

@@ -0,0 +1,131 @@
+# Template Patterns
+
+How production Constellation templates receive children, read configuration, force read-only, lay out columns, group fields and handle hidden children. States are in [state-matrix.md](./state-matrix.md); the code skeleton is in [component-patterns.md](./component-patterns.md); the `config.json` shapes are in [config-schema.md](./config-schema.md).
+
+Use only PCore/PConnect methods documented in the [API catalog](./pcore-pconnect-apis.md). Where this file names a method the catalog does not document, it says so. Cosmos props and components come from a newer Cosmos than customers may have installed, so check the `.d.ts` in `node_modules/@pega/cosmos-react-core` and `@pega/cosmos-react-work` first.
+
+## Children are regions
+
+The `children` prop is **one element per region**, not one per field. Look at what the scaffold does before choosing a layout:
+
+- **Editable layout:** render `children` straight into the Cosmos `Grid`. The platform has already resolved each region; this is what the FORM scaffold does.
+- **Read-only layout:** go one level down. A region's fields are `region.props.getPConnect().getChildren()`, which returns `[{ getPConnect }]`. Render each with `getPConnect().getComponent()`, and read its label and settings with `getPConnect().resolveConfigProps(getPConnect().getConfigProps())`. The DETAILS and FORM scaffolds do this in `DetailsRender.tsx`.
+- **Per-field layout** (column spans, per-field visibility, label/value pairs) always needs the second form, because the region element hides the fields.
+
+Normalize the prop first: `const children = [props.children].flat(Infinity).filter(isValidElement)`.
+
+Find a region by name, not by position: `region.props.getPConnect().getRawMetadata().name`. The generic region names are `A`, `B` and `C` (the PAGE, DETAILS and FORM-region scaffolds), with `Fields` for a single-region form. Fall back to the first child only if the named region is missing. Do not rename these in a copied scaffold; saved views depend on them.
+
+Memoize the element you get from `getComponent()` (`useMemo(() => pConn.getComponent(), [])`). A new element every render remounts the child and loses its focus and state.
+
+A node whose raw metadata `type` is `reference` is a view reference; its content is available through `getReferencedViewPConnect().getPConnect()`. Render a reference child directly, without wrapping it in a label/value pair. Test it with `getRawMetadata().type === 'reference'`, not with private fields.
+
+Never mutate raw child metadata (`getRawMetadata()` objects). Clone it first; a mutation leaks across renders.
+
+## Reading configuration
+
+- Merge inherited props over your own: `const propsToUse = { label, showLabel, ...getPConnect().getInheritedProps() };`. Inherited values win, because a parent view reference can override a child view's heading.
+- Show the label when `showLabel` is true, or when it is unset and the view is editable. In display mode, show it unless `showLabel === false`. Return no heading when there is no label.
+- Numbers and booleans arrive as strings. `NumCols` is a string select (`'1'`, `'2'`, `'3'`): use `parseInt(NumCols, 10) || 1`. Normalize `true | 'true'` for flags, and guard numeric settings with `Number()` plus `Number.isFinite`.
+- `showLabel` defaults differ by template (a form defaults to false, a details view to true); set the default in `defaultConfig` so the property panel matches.
+- Per-child settings are read with `getConfigProps()`: `visibility`, `displayMode`, and layout hints such as `isFormWidth`, `isContainerWidth` and `detailFVLItem`.
+- Localize labels with `PCore.getLocaleUtils().getLocaleValue(label, undefined, localeReference)`; `pConn.getLocalizedValue` is deprecated.
+
+## Forcing read-only
+
+A DETAILS template must make its fields display-only, and the shipped scaffold does it on every region child:
+
+```typescript
+children.forEach((child) => {
+  child.props.getPConnect().setInheritedProp('readOnly', true);
+  child.props.getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY');
+});
+```
+
+Without this a custom DETAILS template shows editable inputs. It is called during render, so it must be idempotent (same values every render, none that depend on a loop variable). `setInheritedProp` takes an optional third argument in the platform source that carries the prop across nested view boundaries; check the installed typedefs before using it, because the catalog documents two arguments.
+
+For a field you create from the template's own configuration (highlighted data), set `field.config.displayMode = 'DISPLAY_ONLY'` on a copy of the metadata before `getPConnect().createComponent(...)`, as the scaffold's `HighlightRender` does.
+
+Branch on **both** `readOnly` and `displayMode === 'DISPLAY_ONLY'`. Do not lay out read-only values with the editable grid (see label alignment below).
+
+## Columns and responsive layout
+
+- Build columns from `Grid` with `minmax(0, 1fr)` tracks. For fixed ratios: `narrowWide` is `minmax(0, 1fr) minmax(0, 2fr)` and `wideNarrow` is `minmax(0, 2fr) minmax(0, 1fr)`. Use those names for a layout property.
+- **Wrap by container width, not viewport width.** A template can sit in a narrow side panel or a modal, so a viewport media query lies. Measure the template's own container with a `ResizeObserver` (create it in `useLayoutEffect` to avoid a first-paint flash, and `disconnect()` it in cleanup). Collapse to one column when the container is narrower than `minFieldWidth * columns + gaps` (production uses a 16rem minimum field width, and a 620px container for two columns in a tab). Compute `rem` in pixels inside the hook, not at module load.
+- Cosmos also offers `useBreakpoint('md')` and responsive `Grid` props (`md={{ container: { cols } }}`). Prefer `Grid` over a hand-written media query.
+- **Block children span the row.** Large controls (`TextArea`, `RichText`, `RadioButtons`, `Checkbox` groups, `Attachment`, `Address`, `Group`, embedded tables and references) get `item={{ colStart: '1', colEnd: cols + 1 }}`. A field config flag `isFormWidth` does the same. Tables (`isContainerWidth`) are lifted out of the column grid into their own block.
+- A long value goes **stacked** (label above) instead of inline: a text area or rich text of about 60 characters or more, an image URL, a map. Otherwise inline.
+- A theme setting that places helper text above the field forces a single column.
+- Nested templates: an embedded view inside a form normally inherits the outer column count rather than starting its own grid. Add an `inheritParentLayout` boolean (and, as the scaffold does, a `templateOverrideMode` select with `USE_TEMPLATE` / `IGNORE_TEMPLATE`) if the template can be nested. Share the outer count through your own React context between your own templates.
+- Do not set `100vh` or a page height. The shell owns scrolling.
+
+### Label alignment in read-only lists
+
+Put consecutive simple fields in **one** `FieldValueList` (or the Cosmos `Details` list) so labels share a column. Separate lists break the alignment. Start a new list at a non-simple child (a nested view, table, group or editable reference). `@pega/cosmos-react-work` exports `Details`, `DetailsList` and `DetailsContext`, which already handle container-width columns, heading depth, `narrowWide` / `wideNarrow` arrangement, an empty-column `EmptyState` and label-column alignment; check whether the installed version has them before hand-building. A Checkbox's label comes from `caption`, not `label`.
+
+## Field groups and headings
+
+- `FieldGroup` with a `name` renders a `fieldset` with a `legend`; without a name it is a plain `div`. The legend is not a heading unless you pass `headingTag`. It also supports `description`, `collapsed` with `onToggleCollapsed` (the button has `aria-expanded`), `status='error'` and `variant='form-group'`.
+- `FieldGroupList` renders an ordered list of groups (a repeating section) with `id`, `headingTag`, `status`, `collapsed` and `onDelete` per item.
+- Wrap in a `FieldGroup` only when there is a label to show. Show **instructions only when a heading is shown** (WCAG 2.4.6 and 3.3.2). The `{ "format": "INSTRUCTIONS" }` property yields an `instructions` prop that can be `'casestep'`, `'none'`, a string, or `{ htmlContent, messageType, dismissBanner }` (`Caution`, `Information` and `Good` map to `Banner` variants `warning`, `info` and `success`). An unprocessed `'@PARAGRAPH ...'` string should be hidden, not shown.
+- Heading levels: the page template owns the `h1`; a top-level section is `h2`; nested content is `h3` and below. Keep them sequential by `Text variant` or `headingTag`.
+- Collapsible row state: keep a `Map<rowId, boolean>` keyed by a stable id (the unique field value, else the index). Seed existing rows from the setting, start rows added later expanded, and no cleanup is needed on delete.
+
+## Hidden, invisible and empty children
+
+- A child with `visibility: false` renders `null`, but your wrapper cell stays and leaves an empty gap. Hide the whole cell, and hide the whole block when every cell is hidden.
+- A view or group whose children are all hidden collapses, and its heading must disappear too. Write a local `hasVisibleChild` over `getChildren()` using `isVisible()` and `getConfigProps().visibility !== false`.
+- A template that reads `isVisible()` in render may not re-render when a child's visibility flips, because the platform's connect layer is internal. If it matters, register a value with `registerAdditionalProps` (documented) so the template re-renders, and test the flip.
+- Empty states: show `EmptyState` when every region has no children. If every child is an Insight, or a single Pulse, skip the surrounding `Card` so it is not double-wrapped.
+- One broken child does not break its siblings as long as you render the elements the platform created; the platform wraps each in an error boundary. Do not add your own boundary around them, which would hide errors the platform surfaces.
+
+## Tabs
+
+Use Cosmos `Tabs` and `TabPanel`. They already provide `role=tablist`, `aria-orientation`, `role=tab` with `aria-selected` and `aria-controls`, a roving `tabIndex`, Arrow-key navigation, `role=tabpanel` with `aria-labelledby`, and `inert` on inactive panels. Do not reimplement them.
+
+- `tabs` entries are `{ id, name, count?, errors?, disabled?, href? }`. Ids become DOM ids; keep them unique and stable (`${viewName}-${name}-${index}`, or a unique field value for row tabs).
+- Active tab: keep the current tab if it is still visible, otherwise fall back to the first visible one. Re-run this when visibility or the data changes, so deleting the active tab never leaves a dangling id.
+- Vertical tabs only at `md` and up: `useBreakpoint('md') ? type : 'horizontal'`.
+- Create content lazily for display tabs, and mount all tabs for editable forms (validation needs every field).
+- Persist the active tab with `PCore.getNavigationUtils().setComponentState(key, state)` and read it with `getComponentState`; derive the key from the case and view names. Remove it with `removeComponentState` when it is no longer needed.
+- Style with `[aria-orientation='vertical']` and `[role]` selectors. Do not deep-import Cosmos internals (`StyledTab`, `lib/components/...`); they are not public API.
+
+## PAGE templates
+
+Delegate to the public Cosmos page templates: `OneColumnPage`, `TwoColumnPage`, `ThreeColumnPage`, `WideNarrowPage`, `NarrowWidePage`, `TabbedPage` and `DynamicLayoutPage`. Their common props are `title`, `icon`, `actions`, `banners`, `path`, `header`, `utilities` and the region slots `a`, `b`, `c`. Pass region elements straight into the slots.
+
+- Offer the layout as a `SELECT` (`one-column`, `two-column`, `narrow-wide`, `wide-narrow`) and show the region B picker only for layouts that use it (`"visibility": "$this.layout == 'two-column'"`).
+- Cosmos owns scrolling, the `md` breakpoint, sticky regions and heading focus. Do not set `document.title` (the platform sets it) and do not move focus to the heading yourself.
+- Add no `<main>` or other landmark; the shell owns them.
+
+## Passing context to children
+
+- `setInheritedProp(name, value)` on the template or a child (documented), and `setInheritedConfig` (documented).
+- `registerAdditionalProps({ key: '@P caseInfo.lastUpdateTime' })` pushes a store value in as a prop (documented).
+- Your own React context between your own components, and `DetailsContext` from `@pega/cosmos-react-work` if you use `Details`.
+- Scope pub/sub events to an instance id so two forms on a page do not react to each other (see [widget-patterns.md](./widget-patterns.md)).
+- When a local and an inherited prop collide, the inherited one wins.
+
+## Memoization
+
+- `useMemo` the heavy trees (the content element, the tab array, highlighted data) with the real inputs as dependencies. Memoize context values you provide.
+- Call hooks **before** any early return. A read-only early return placed above a hook breaks the call order.
+- Key children by `getRawMetadata().config.value` or `.name`, with the index as a last resort. Do not use a random id (`createUID()` or `crypto.randomUUID()`) as a key; it remounts every render.
+
+## List and table templates
+
+Pega's list templates sit on internal libraries and cannot be reproduced by a customer, so there is little to copy. The transferable parts: identify rows by a unique field (or index), and use that id for keys, collapse state, tab ids and deletion (re-find the row by id, because indexes shift); keep the latest values in refs for stable callbacks; subscribe with a per-instance id and always unsubscribe; and when the last row is deleted while focus was inside the table, move focus to the Add button.
+
+## Traps
+
+1. `getComponent()` in render without `useMemo` remounts the child.
+2. Indexing `children[i]` instead of finding a region by name.
+3. A section heading shown over an all-hidden view.
+4. Mutating raw child metadata.
+5. A `display:none` cell breaking `:last-child` margin logic; with `Grid` gap, hide the item rather than relying on margins.
+6. `displayMode` also arrives on embedded data views; handle `mode === 'editable'` together with `displayMode`.
+7. Reading `NumCols` as a number when it is a string.
+8. Cosmos deep imports from `lib/components/...`.
+9. Setting the document title or focusing the heading in a PAGE template.
+10. Calling `setInheritedProp` with a changing value in a loop during render.
+11. Reading `oneRem` in pixels at module load, and forgetting to disconnect a `ResizeObserver`.