@dextinity/agent-features 2.0.0-canary-20260729062014

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 package (see [Step 2](../SKILL.md#step-2--discover-the-project) for how to detect one).
+
+---
+
+## Imports
+
+```tsx
+import {
+    BlocksBlock,
+    hasRichTextBlockContent,
+    ListBlock,
+    OneOfBlock,
+    OptionalBlock,
+    PreviewSkeleton,
+    type PropsWithData,
+    SvgImageBlock,
+    type SupportedBlocks,
+    withPreview,
+} from "@dextinity/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 `@dextinity` package. It uses the site-specific wrapper, typically at `@src/common/blocks/DamImageBlock`:
+
+```tsx
+// Wrong: import from cms-api
+import { DamImageBlock } from "@dextinity/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 `@dextinity/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`             |

package/skills/comet-core-admin-component-authoring/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: comet-core-admin-component-authoring
+description: Authoring or changing a component in @dextinity/admin or a sibling package that uses its slot and theme machinery (admin-color-picker, admin-date-time, admin-rte) so it supports MUI-style customization: per-instance sx/className overrides, theme styleOverrides, and defaultProps. Use whenever adding a new component or editing an existing one's slots, props, class keys, overridable icons, or theme-type registration — even for small changes.
+metadata:
+    internal: true
+---
+
+# Authoring customizable @dextinity/admin components
+
+Every component shipped from `@dextinity/admin` and its sibling packages must be
+customizable the same way MUI components are: consumers can override a single
+instance (`sx`/`className`), restyle every instance through the theme
+(`styleOverrides`), and set default props through the theme (`defaultProps`). This
+only works if the component is built with the slot/theme machinery. A component
+that hardcodes its markup and styling looks fine in isolation but silently breaks all
+three customization paths, and the gap is only found later, once someone tries to
+customize it. Add the customization from the start.
+
+This applies to any component built with the slot and theme machinery —
+`createComponentSlot` and `ThemedComponentBaseProps`, both from `@dextinity/admin`. Today
+that means components in `@dextinity/admin` and the sibling packages that use it:
+`admin-color-picker`, `admin-date-time`, `admin-rte`. Other packages under
+`packages/admin/`, such as `cms-admin`, don't use this pattern and are out of scope.
+
+## How to use this skill
+
+Read the reference doc for how to build the component, then use the checklist below as a
+verification pass over what you wrote — it is the list of things that are easy to miss
+and that otherwise get caught only in review. The reference doc is the single source for the
+conventions and their worked code examples:
+
+`docs/docs/8-comet-core-development/1-creating-customizable-admin-components.md`
+
+Every item below points at a section of that doc. When an item here and the doc disagree,
+follow the doc — and tell the user so this checklist can be corrected.
+
+## When not to use this skill
+
+If you are building admin UI in a **project that consumes** `@dextinity/admin` (pages,
+dashboards, dialogs, composing existing components), use the **`comet-admin-ui`** skill
+instead — that is a different job with different rules. This skill is only for authoring
+the library's own components.
+
+## Verification checklist
+
+Each item names a rule and why it matters; the doc has the exact syntax for each.
+
+1. **`index.ts` exports the component, its props type (`<Name>Props`), and its class-key
+   type (`<Name>ClassKey`).** Consumers need the props and class-key types to type their
+   theme overrides.
+
+2. **The `ClassKey` type lists every visual slot and every modifier/variant state, with
+   `root` as the outermost slot.** These become the stable, prefixed class names consumers
+   target, so they belong in the public type.
+
+3. **Each slot is built with `createComponentSlot`**, passing the base element/component,
+   the `componentName`, and the `slotName`. This is what connects the slot to
+   `styleOverrides` and produces the deterministic class name.
+
+4. **The props type extends `ThemedComponentBaseProps`**, with a generic mapping each slot
+   name to its base element/component. This is what gives consumers `slotProps` and the
+   root `sx`/`className`. Each key's value type must be the same element or component
+   passed to `createComponentSlot` for that slot — the two are declared separately, so a
+   mismatch types that slot's `slotProps` against the wrong component.
+
+5. **Props are read through `useThemeProps`, never the raw `inProps`, with the name
+   prefixed `CometAdmin`.** This merges the theme's `defaultProps` with the passed props —
+   skip it and `defaultProps` customization is dead.
+
+6. **`slotProps?.<slot>` is spread into each slot, and `restProps` (carrying `sx` and
+   `className`) into the `root` slot — after the slot's hardcoded props.** Spreading after
+   is what lets consumers override; the exception is props that must never be overridden,
+   which go last. This ordering is easy to get wrong.
+
+7. **Style-affecting values are passed through `ownerState`** to the slots that need them,
+   rather than writing conditional styling into the markup.
+
+8. **Conditional modifier class names come from `classesResolver(ownerState)`**, returning
+   the relevant class keys. This lets consumers target a state from outside the component.
+
+9. **Icons are overridable via an `iconMapping` prop** — an object whose keys say what each
+   icon is for. Destructure with an `Icon` suffix and a default, so the component works
+   with no mapping but every icon can be replaced.
+
+10. **The component is registered in MUI's theme types** — the `CometAdmin<Name>` key added
+    to `ComponentsPropsList`, `ComponentNameToClassKey`, and `Components` (with
+    `defaultProps?: Partial<...>` and `styleOverrides`). Without this, consumers get no type
+    safety on their overrides.
+
+Two final checks that catch the most frequent review findings: the `CometAdmin<Name>` name
+is identical in `useThemeProps` and in all three theme-type interfaces, and the package
+type-checks (`tsc`) — the theme-type augmentation is the usual failure point.