@comet/agent-features 9.0.0-beta.5

package/skills/comet-block/references/select.md

@@ -0,0 +1,176 @@
+# Select Field Patterns
+
+Comet-specific patterns for select (dropdown) fields. Load this file when a block contains a select/enum field.
+
+The basic enum definition (`export enum Variant { ... }`, `@IsEnum`, `@BlockField({ type: "enum" })`) is covered in api-patterns.md. The full `createCompositeBlockSelectField` options table is in admin-patterns.md. This file covers the **unique patterns** only.
+
+---
+
+## Numeric Select (Non-Enum)
+
+Select fields work for `number` values too — no enum needed in the API. Use `@IsInt` (or `@IsNumber`) instead of `@IsEnum`, and plain `number` as the TypeScript type.
+
+**API:**
+
+```ts
+class ExampleBlockData extends BlockData {
+    @BlockField()
+    overlay: number;
+}
+
+class ExampleBlockInput extends BlockInput {
+    @IsInt()
+    @Min(0)
+    @Max(90)
+    @BlockField()
+    overlay: number;
+
+    transformToBlockData(): ExampleBlockData {
+        return blockInputToData(ExampleBlockData, this);
+    }
+}
+```
+
+**Admin** — use `FormattedNumber` for locale-aware labels:
+
+```tsx
+const overlayOptions: Array<{ value: ExampleBlockData["overlay"]; label: ReactNode }> = [
+    { value: 90, label: <FormattedNumber value={0.9} style="percent" /> },
+    { value: 70, label: <FormattedNumber value={0.7} style="percent" /> },
+    { value: 50, label: <FormattedNumber value={0.5} style="percent" /> },
+    { value: 30, label: <FormattedNumber value={0.3} style="percent" /> },
+    { value: 0,  label: <FormattedNumber value={0}   style="percent" /> },
+];
+
+overlay: {
+    block: createCompositeBlockSelectField<ExampleBlockData["overlay"]>({
+        defaultValue: 50,
+        options: overlayOptions,
+    }),
+    title: <FormattedMessage id="exampleBlock.overlay" defaultMessage="Overlay" />,
+},
+```
+
+> Pass percentages as fractions (`0.9` for 90%) to `FormattedNumber`.
+
+---
+
+## Generated Options (`.map`)
+
+When options follow a regular pattern, generate them programmatically instead of listing each manually:
+
+```tsx
+titleHtmlTag: {
+    block: createCompositeBlockSelectField<ExampleItemBlockData["titleHtmlTag"]>({
+        label: <FormattedMessage id="exampleItemBlock.titleHtmlTag" defaultMessage="Title HTML tag" />,
+        defaultValue: "h3",
+        options: ([1, 2, 3, 4, 5, 6] as const).map((level) => ({
+            value: `h${level}` as ExampleItemBlockData["titleHtmlTag"],
+            label: <FormattedMessage id="exampleItemBlock.headline" defaultMessage="Headline {level}" values={{ level }} />,
+        })),
+        required: true,
+    }),
+},
+```
+
+---
+
+## `label` vs `title` — Mutual Exclusivity
+
+| Scenario                                                               | Use                                                               |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Field has its own inline label (visible inside the dropdown component) | `label` on the field options; **omit** `title` on the block entry |
+| No inline label                                                        | **Omit** `label`; use `title` on the block entry instead          |
+
+Using both creates redundant, stacked headings.
+
+```tsx
+// label only — no title
+variant: {
+    block: createCompositeBlockSelectField<ExampleBlockData["variant"]>({
+        label: <FormattedMessage id="exampleBlock.variant" defaultMessage="Variant" />,
+        defaultValue: "contained",
+        options: variantOptions,
+    }),
+},
+
+// title only — no label
+alignment: {
+    block: createCompositeBlockSelectField<ExampleBlockData["alignment"]>({
+        defaultValue: "left",
+        options: alignmentOptions,
+    }),
+    title: <FormattedMessage id="exampleBlock.alignment" defaultMessage="Alignment" />,
+},
+```
+
+---
+
+## Multi-Select
+
+**API** — add `array: true` to `@BlockField` and `{ each: true }` to `@IsEnum`:
+
+```ts
+class MyBlockData extends BlockData {
+    @BlockField({ type: "enum", enum: Category, array: true })
+    categories: Category[];
+}
+
+class MyBlockInput extends BlockInput {
+    @IsEnum(Category, { each: true })
+    @BlockField({ type: "enum", enum: Category, array: true })
+    categories: Category[];
+    ...
+}
+```
+
+An empty array `[]` is valid — `{ each: true }` passes on zero elements.
+
+**Admin** — set `multiple: true` and `defaultValue: []`:
+
+```tsx
+categories: {
+    block: createCompositeBlockSelectField<MyBlockData["categories"]>({
+        label: <FormattedMessage id="myBlock.categories" defaultMessage="Categories" />,
+        defaultValue: [],
+        options: [
+            { value: "news",  label: <FormattedMessage id="myBlock.categories.news"  defaultMessage="News" /> },
+            { value: "blog",  label: <FormattedMessage id="myBlock.categories.blog"  defaultMessage="Blog" /> },
+            { value: "event", label: <FormattedMessage id="myBlock.categories.event" defaultMessage="Event" /> },
+        ],
+        multiple: true,
+    }),
+},
+```
+
+---
+
+## `required` Option
+
+`required: true` removes the empty/placeholder option from the dropdown — the user must always have a value selected.
+
+Use it for fields with no meaningful "none" state (e.g., HTML tag choice). For most enum fields, prefer `defaultValue` over `required` — this keeps the block savable immediately while still letting users change the value.
+
+---
+
+## Default Value Rules
+
+| Scenario                       | `defaultValue`                                                   |
+| ------------------------------ | ---------------------------------------------------------------- |
+| Single select, logical default | Most common/neutral value (`"left"`, `"contained"`, `"default"`) |
+| HTML tag select                | Most semantically common tag (`"h3"`)                            |
+| Numeric select                 | Middle or most common value (`50` for overlay percentage)        |
+| Multi-select                   | `[]`                                                             |
+
+Enum fields are always required in the API (`@IsEnum` rejects `undefined`), so the Admin **must** provide a `defaultValue`.
+
+---
+
+## Common Pitfalls
+
+1. **`label` and `title` both set** — creates duplicate headings; use one or the other.
+2. **Multi-select: missing `{ each: true }`** — `@IsEnum(MyEnum)` without it rejects arrays.
+3. **Multi-select: missing `array: true` in `@BlockField`** — field serialises as a single value instead of an array.
+4. **Missing `defaultValue`** — block fails to save on first add because `@IsEnum` rejects `undefined`.
+5. **Enum not exported** — must be exported from the API file to appear in the generated GraphQL schema and `@src/blocks.generated` types.
+6. **`@IsOptional()` on an enum field** — enum fields must always have a value; making them optional creates an API/Admin inconsistency.

package/skills/comet-block/references/site-patterns.md

@@ -0,0 +1,202 @@
+# Site Block Patterns
+
+Comet-specific conventions for the site layer. All site blocks live in `{BlockName}Block.tsx` (PascalCase) under `site/src/`, typically `documents/pages/blocks/` or `common/blocks/`.
+
+Skip site block creation when the project has no `site` directory.
+
+---
+
+## Imports
+
+```tsx
+import {
+    BlocksBlock,
+    hasRichTextBlockContent,
+    ListBlock,
+    OneOfBlock,
+    OptionalBlock,
+    PreviewSkeleton,
+    type PropsWithData,
+    SvgImageBlock,
+    type SupportedBlocks,
+    withPreview,
+} from "@comet/site-nextjs";
+import { type MyBlockData } from "@src/blocks.generated";
+```
+
+`@src/blocks.generated` types are auto-generated from the API layer — always import with `type`, never maintain manually.
+
+---
+
+## withPreview
+
+Wrap **every** site block with `withPreview`. This enables the admin preview overlay. The `label` appears in the overlay.
+
+```tsx
+export const MyBlock = withPreview(
+    ({ data: { title, image } }: PropsWithData<MyBlockData>) => (
+        <div>
+            <h2>{title}</h2>
+            <DamImageBlock data={image} aspectRatio="16x9" />
+        </div>
+    ),
+    { label: "My Block" },
+);
+```
+
+**Exception:** Top-level `PageContentBlock` and `PageContent`-wrapper variants are **not** wrapped with `withPreview` — they delegate to the inner block which is already wrapped.
+
+---
+
+## DamImageBlock Site Wrapper
+
+The site layer does **not** use `DamImageBlock` from a `@comet` package. It uses the site-specific wrapper, typically at `@src/common/blocks/DamImageBlock`:
+
+```tsx
+// Wrong: import from cms-api
+import { DamImageBlock } from "@comet/cms-api";
+
+// Correct: import site wrapper
+import { DamImageBlock } from "@src/common/blocks/DamImageBlock";
+```
+
+Always pass `aspectRatio`. Optionally pass `sizes` for responsive images:
+
+```tsx
+<DamImageBlock data={image} aspectRatio="16x9" sizes="(max-width: 768px) 100vw, 50vw" />
+```
+
+---
+
+## Guarding Optional Content
+
+**Rich text** — always use `hasRichTextBlockContent`. Never render a `RichTextBlock` without this guard:
+
+```tsx
+{
+    hasRichTextBlockContent(description) && <RichTextBlock data={description} />;
+}
+```
+
+**SVG image blocks** — check `damFile`:
+
+```tsx
+{
+    icon.damFile && <SvgImageBlock data={icon} width={48} height={48} />;
+}
+```
+
+**Nullable strings** — standard JS truthiness:
+
+```tsx
+{
+    title && <h2>{title}</h2>;
+}
+```
+
+`BlocksBlock`, `ListBlock`, `OneOfBlock`, and `OptionalBlock` handle their own empty states — no guard needed.
+
+---
+
+## BlocksBlock (PageContentBlock)
+
+Define `supportedBlocks` as a **module-level constant**, never inside the component body (prevents recreation on every render).
+
+Keys must exactly match the API and Admin layer keys.
+
+```tsx
+const supportedBlocks: SupportedBlocks = {
+    richText: (props) => <StandaloneRichTextBlock data={props} />,
+    heading: (props) => <StandaloneHeadingBlock data={props} />,
+    media: (props) => <StandaloneMediaBlock data={props} />,
+};
+
+export const PageContentBlock = ({ data }: PropsWithData<PageContentBlockData>) => {
+    return <BlocksBlock data={data} supportedBlocks={supportedBlocks} />;
+};
+```
+
+---
+
+## ListBlock
+
+Pass the entire `data` object (not `data.blocks`). To access item count, use `data.blocks.length` alongside the `ListBlock`:
+
+```tsx
+export const FeatureListBlock = withPreview(
+    ({ data }: PropsWithData<FeatureListBlockData>) => (
+        <div style={{ "--list-item-count": data.blocks.length }}>
+            <ListBlock data={data} block={(block) => <FeatureItemBlock data={block} />} />
+        </div>
+    ),
+    { label: "Feature List" },
+);
+```
+
+---
+
+## OneOfBlock and OptionalBlock
+
+See [block-types.md](block-types.md) for full usage. Quick reference:
+
+- `OneOfBlock` — renders the selected block from a mutually exclusive set. Returns `null` when nothing is selected.
+- `OptionalBlock` — renders a block with a visibility toggle. Returns `null` when `visible` is `false`.
+
+Both accept a `supportedBlocks` map defined at module level.
+
+---
+
+## Standalone and PageContent Wrapper Pattern
+
+When a block appears in both `PageContentBlock` (needs layout wrapper) and other contexts (layout provided by parent), export two components:
+
+```tsx
+// Inner block — used standalone or nested; always withPreview
+export const StandaloneHeadingBlock = withPreview(
+    ({ data: { heading } }: PropsWithData<StandaloneHeadingBlockData>) => (
+        <div>
+            <HeadingBlock data={heading} />
+        </div>
+    ),
+    { label: "Heading" },
+);
+
+// PageContent wrapper — adds layout; NOT withPreview (delegates to inner)
+export const PageContentStandaloneHeadingBlock = (props: PropsWithData<StandaloneHeadingBlockData>) => (
+    <PageLayout grid>
+        <div className={styles.pageLayoutContent}>
+            <StandaloneHeadingBlock {...props} />
+        </div>
+    </PageLayout>
+);
+```
+
+Register the `PageContent`-prefixed variant in the `PageContentBlock` `supportedBlocks` map and the plain variant wherever the block appears nested in other blocks.
+
+---
+
+## "use client" Directive
+
+Add `"use client"` at the top of the file when the block uses:
+
+- React hooks (`useState`, `useEffect`, `useRef`, `useId`, `useContext`, etc.)
+- Event handlers (`onClick`, `onChange`, etc.)
+- Client-only library imports
+- `usePreview()` from `@comet/site-nextjs`
+
+Most simple composite and list blocks do **not** need `"use client"`.
+
+---
+
+## Naming Conventions
+
+| Element                | Convention                                               | Example                             |
+| ---------------------- | -------------------------------------------------------- | ----------------------------------- |
+| File name              | PascalCase ending in `Block.tsx`                         | `ProductCardBlock.tsx`              |
+| Exported constant      | `{BlockName}Block`                                       | `ProductCardBlock`                  |
+| `withPreview` label    | Short human-readable name                                | `"Stage"`, `"Feature Item"`         |
+| `supportedBlocks` keys | camelCase, matching API and Admin keys exactly           | `richText`, `heading`               |
+| CSS module file        | `{BlockName}Block.module.scss`                           | `ProductCardBlock.module.scss`      |
+| Data type import       | `type {BlockName}BlockData` from `@src/blocks.generated` | `type ProductCardBlockData`         |
+| PageContent wrapper    | `PageContent{BlockName}Block`                            | `PageContentStandaloneHeadingBlock` |
+| Local/nested blocks    | Descriptive PascalCase, not exported                     | `AccordionContentBlock`             |