canopycms 0.4.0 → 0.6.0

package/dist/config/types.d.ts

@@ -9,6 +9,7 @@ import type { LogicalPath, ContentId } from '../paths/types.js';
 import type { PermissionPath } from '../authorization/types.js';
 import type { EntryLinkUrlResolver } from '../entry-link-resolver.js';
 import type { CropRect } from '../assets/transform-directives.js';
+import type { SeoFieldLocation } from '../static/seo.js';
 declare const scalarFieldTypes: readonly ["string", "number", "boolean", "datetime", "code"];
 export declare const markdownFieldTypes: readonly ["markdown", "mdx"];
 export declare const primitiveFieldTypes: readonly ["string", "number", "boolean", "datetime", "code", "markdown", "mdx"];
@@ -52,6 +53,13 @@ interface BaseFieldConfig {
      * `includeBody: true`.
      */
     isBody?: boolean;
+    /**
+     * On a `list: true` field or a `block` field: the most items the list may hold. The editor
+     * stops adding at the cap, saving over it is refused, and a static build fails on an entry
+     * over it, so adding a cap to a list that already holds more fails the build until the
+     * content is fixed. `ensureMaxItemsPlacement` (`validation.ts`) refuses it elsewhere in a registry schema.
+     */
+    maxItems?: number;
 }
 interface PrimitiveFieldConfig extends BaseFieldConfig {
     type: (typeof scalarFieldTypes)[number];
@@ -136,7 +144,29 @@ export interface ReferenceFieldConfig extends BaseFieldConfig {
      * to different shapes in different places.
      */
     includeBody?: boolean;
+    /** Order of the picker's options. Default `'label'`. See {@link ReferenceOptionSort}. */
+    optionSort?: ReferenceOptionSort;
 }
+/**
+ * How a reference picker orders its options. Every mode runs after the search filter.
+ *
+ * - `'label'`: alphabetical by label.
+ * - `'collection'`: one group per collection, in content-tree order (a collection, then its
+ *   subcollections), each in its collection's own order, then by label.
+ * - `{ field, direction }`: by the target's value at `field`, a dotted path for a nested field
+ *   (`'meta.publishedAt'`). Numbers compare as numbers and sort before strings (`'desc'` reverses that too); strings compare
+ *   as plain text, so point it at an ISO date (`YYYY-MM-DD`; unquoted frontmatter dates count):
+ *   a display date like `'March 4'` sorts by month name. An entry with no value sorts first
+ *   under `'desc'`, last under `'asc'` (the default). Ties go by label.
+ *
+ * @example
+ * // Newest first, with entries not yet given a date at the top.
+ * optionSort: { field: 'publishedAt', direction: 'desc' }
+ */
+export type ReferenceOptionSort = 'label' | 'collection' | {
+    field: string;
+    direction?: 'asc' | 'desc';
+};
 /**
  * Image field config. The value is a structured object (see `ImageFieldValue`
  * below), not a bare URL string.
@@ -460,6 +490,8 @@ export interface CanopyConfig {
     validateEntry?: ValidateEntryHook;
     /** Site default for every field checked as MDX — see {@link CanopyConfigInput.mdxAllow}. */
     mdxAllow?: MdxAllowlist;
+    /** Where entries keep their SEO fields — see {@link CanopyConfigInput.seo}. */
+    seo?: SeoFieldLocation;
     /** Dev-mode-only behavior — see {@link CanopyConfigInput.dev}. */
     dev?: DevConfig;
 }
@@ -549,6 +581,13 @@ export interface CanopyConfigInput {
     validateEntry?: ValidateEntryHook;
     /** What every field checked as MDX accepts; a field's own `mdxAllow` replaces it key by key. */
     mdxAllow?: MdxAllowlist;
+    /**
+     * Where entries keep their SEO fields: `group` when `defineSeoFieldGroup({ group })` nests
+     * them, `fields` for renamed ones. Omit for the flat default. Every surface that reads an
+     * entry's `noindex` reads it here: the sitemap and page metadata helpers `createNextCanopyContext`
+     * returns, AI content and the editor's reference picker.
+     */
+    seo?: SeoFieldLocation;
     /** Dev-mode-only behavior (content-sync divergence detection). Ignored when mode !== 'dev'. */
     dev?: DevConfig;
 }

package/dist/config/validation.d.ts

@@ -62,6 +62,12 @@ export declare const ensureNoGroupsInsideComplexFields: (fields: unknown) => voi
  * never be saved empty, so it would never be stamped. Throws on the first problem.
  */
 export declare const ensureStampOnPublishPlacement: (fields: unknown, scopeLabel?: string) => void;
+/**
+ * Check that `maxItems` is a positive whole number on a field that holds items: a `list: true`
+ * field or a `block` field. Recurses into groups, objects and block templates like
+ * `ensureStampOnPublishPlacement`. Throws on the first problem.
+ */
+export declare const ensureMaxItemsPlacement: (fields: unknown, scopeLabel?: string) => void;
 /**
  * Check every markdown and mdx field's `mdxAllow` against its schema and its `renderAs`,
  * `mdxAllow` and `executable` against each other. Throws on the first problem.

package/dist/config/validation.js

@@ -294,6 +294,39 @@ export const ensureStampOnPublishPlacement = (fields, scopeLabel = 'entry schema
     };
     check(fields, undefined);
 };
+/**
+ * Check that `maxItems` is a positive whole number on a field that holds items: a `list: true`
+ * field or a `block` field. Recurses into groups, objects and block templates like
+ * `ensureStampOnPublishPlacement`. Throws on the first problem.
+ */
+export const ensureMaxItemsPlacement = (fields, scopeLabel = 'entry schema') => {
+    const refuse = (f, why) => {
+        throw new Error(`${scopeLabel}: field "${f.name ?? 'unknown'}" has maxItems, ${why}`);
+    };
+    const check = (scopeFields) => {
+        if (!Array.isArray(scopeFields))
+            return;
+        for (const field of scopeFields) {
+            const f = field;
+            if (f?.maxItems !== undefined) {
+                if (typeof f.maxItems !== 'number' || !Number.isInteger(f.maxItems) || f.maxItems < 1) {
+                    refuse(f, 'which must be a positive whole number');
+                }
+                if (f.list !== true && f.type !== 'block') {
+                    refuse(f, 'but it is not a list; only a `list: true` field or a block field holds items');
+                }
+            }
+            if (f?.type === 'group' || f?.type === 'object')
+                check(f.fields);
+            if (f?.type === 'block' && Array.isArray(f.templates)) {
+                for (const template of f.templates) {
+                    check(template.fields);
+                }
+            }
+        }
+    };
+    check(fields);
+};
 /**
  * Check every markdown and mdx field's `mdxAllow` against its schema and its `renderAs`,
  * `mdxAllow` and `executable` against each other. Throws on the first problem.

package/dist/editor/FormRenderer.js

@@ -16,6 +16,7 @@ import { DateTimeField } from './fields/DateTimeField.js';
 import { BlockField } from './fields/BlockField.js';
 import { SelectField } from './fields/SelectField.js';
 import { ReferenceField } from './fields/ReferenceField.js';
+import { ReferenceListField } from './fields/ReferenceListField.js';
 import { CodeField } from './fields/CodeField.js';
 import { ImageField } from './fields/ImageField.js';
 import { ObjectField } from './fields/ObjectField.js';
@@ -201,7 +202,7 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
         switch (field.type) {
             case 'string':
                 if (field.list) {
-                    return wrapWithComments(_jsx(StringListField, { id: fieldId, label: label, description: field.description, value: Array.isArray(currentValue) ? currentValue : [], onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly }, fieldKey(path)));
+                    return wrapWithComments(_jsx(StringListField, { id: fieldId, label: label, description: field.description, value: Array.isArray(currentValue) ? currentValue : [], onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly, maxItems: field.maxItems }, fieldKey(path)));
                 }
                 return wrapWithComments(_jsx(TextField, { id: fieldId, label: label, description: field.description, value: currentValue ?? '', onChange: update, dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly }, fieldKey(path)));
             case 'boolean':
@@ -210,7 +211,7 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
                 if (field.list) {
                     return wrapWithComments(_jsx(NumberListField, { id: fieldId, label: label, description: field.description, value: Array.isArray(currentValue)
                             ? currentValue.filter((v) => typeof v === 'number')
-                            : [], onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly }, fieldKey(path)));
+                            : [], onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly, maxItems: field.maxItems }, fieldKey(path)));
                 }
                 return wrapWithComments(_jsx(NumberField, { id: fieldId, label: label, description: field.description, value: typeof currentValue === 'number' ? currentValue : undefined, onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly }, fieldKey(path)));
             case 'datetime':
@@ -229,22 +230,23 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
                         ? Array.isArray(currentValue)
                             ? currentValue
                             : []
-                        : (currentValue ?? ''), multiple: isMulti, onChange: (next) => update(next), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly }, fieldKey(path)));
+                        : (currentValue ?? ''), multiple: isMulti, onChange: (next) => update(next), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly, maxItems: isMulti ? selectField.maxItems : undefined }, fieldKey(path)));
             }
             case 'reference': {
                 const referenceField = field;
                 const staticOptions = referenceField.options
                     ? normalizeOptions(referenceField.options)
                     : undefined;
-                const isMulti = Boolean(referenceField.list);
-                return wrapWithComments(_jsx(ReferenceField, { id: fieldId, label: label, description: field.description, options: staticOptions?.map((opt) => ({
-                        label: opt.label,
-                        value: opt.value,
-                    })), collections: referenceField.collections, entryTypes: referenceField.entryTypes, displayField: referenceField.displayField, branch: branch, value: isMulti
-                        ? Array.isArray(currentValue)
-                            ? currentValue
-                            : []
-                        : (currentValue ?? ''), multiple: isMulti, onChange: (next) => update(next), dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly }, fieldKey(path)));
+                if (referenceField.list) {
+                    return wrapWithComments(_jsx(ReferenceListField, { id: fieldId, label: label, description: field.description, required: field.required, options: staticOptions, collections: referenceField.collections, entryTypes: referenceField.entryTypes, displayField: referenceField.displayField, branch: branch, optionSort: referenceField.optionSort, value: Array.isArray(currentValue) ? currentValue : [], onChange: (next) => update(next), path: path, canopyPath: canopyPath, readOnly: readOnly, resetKey: boundaryResetKey, maxItems: referenceField.maxItems, itemError: (index) => fieldErrors?.[normalizeCanopyPath([...path, index])], onRemoved: (index, id, title) => onRemoved?.({
+                            kind: 'list-item',
+                            listPath: path,
+                            index,
+                            item: id,
+                            label: `"${title}" from ${label}`,
+                        }) }, fieldKey(path)));
+                }
+                return wrapWithComments(_jsx(ReferenceField, { id: fieldId, label: label, description: field.description, options: staticOptions, collections: referenceField.collections, entryTypes: referenceField.entryTypes, displayField: referenceField.displayField, branch: branch, optionSort: referenceField.optionSort, value: currentValue ?? '', onChange: (next) => update(next), dataCanopyField: canopyPath, readOnly: readOnly }, fieldKey(path)));
             }
             case 'image': {
                 const imageField = field;
@@ -256,7 +258,7 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
             }
             case 'block': {
                 const blockField = field;
-                return wrapWithComments(_jsx(BlockField, { label: label, required: field.required, description: field.description, templates: blockField.templates, value: (Array.isArray(currentValue) ? currentValue : []), onChange: (next) => update(next), renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly, resetKey: boundaryResetKey, hasErrors: rowHasErrors(path), onRemoved: (index, block) => {
+                return wrapWithComments(_jsx(BlockField, { label: label, required: field.required, description: field.description, templates: blockField.templates, value: (Array.isArray(currentValue) ? currentValue : []), onChange: (next) => update(next), renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path), readOnly: readOnly, resetKey: boundaryResetKey, hasErrors: rowHasErrors(path), maxItems: blockField.maxItems, onRemoved: (index, block) => {
                         const template = blockField.templates.find((t) => t.name === block.template);
                         onRemoved?.({
                             kind: 'list-item',

package/dist/editor/copy.d.ts

@@ -19,3 +19,8 @@ export declare const EDITOR_ACTIONS: {
     readonly changeUrl: "Change URL";
     readonly changeSlug: "Change slug";
 };
+/**
+ * Why a list at its `maxItems` adds nothing more, as a disabled Add's Tooltip or an input's hint.
+ * `one` and `many` name what the list holds.
+ */
+export declare const listFullReason: (maxItems: number, one?: string, many?: string) => string;

package/dist/editor/copy.js

@@ -19,3 +19,8 @@ export const EDITOR_ACTIONS = {
     changeUrl: 'Change URL',
     changeSlug: 'Change slug',
 };
+/**
+ * Why a list at its `maxItems` adds nothing more, as a disabled Add's Tooltip or an input's hint.
+ * `one` and `many` name what the list holds.
+ */
+export const listFullReason = (maxItems, one = 'item', many = 'items') => `This list holds at most ${maxItems} ${maxItems === 1 ? one : many}. Remove one to add another.`;

package/dist/editor/fields/BlockField.d.ts

@@ -26,6 +26,8 @@ export interface BlockFieldProps {
     hasErrors?: (index: number) => boolean;
     /** Told of each block Remove takes out, so the caller can offer Undo. */
     onRemoved?: (index: number, block: BlockInstance) => void;
+    /** The most blocks the list holds; at it, every add control is disabled and says why. */
+    maxItems?: number;
 }
 export declare const BlockField: React.FC<BlockFieldProps>;
 export {};

package/dist/editor/fields/BlockField.js

@@ -1,12 +1,13 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useId, useRef, useState } from 'react';
-import { ActionIcon, Box, Button, Group, Menu, Paper, ScrollArea, Stack, Text, Tooltip, } from '@mantine/core';
+import { ActionIcon, Box, Button, Group, Menu, Paper, ScrollArea, Stack, Text, Tooltip, VisuallyHidden, } from '@mantine/core';
 import { useMediaQuery } from '@mantine/hooks';
 import { IconPlus } from '@tabler/icons-react';
 import { ITEM_KEY, mintItemKey, withFreshItemKeys } from '../../item-keys.js';
 import { isPlainRecord } from '../../validation/field-traversal.js';
 import { formatCanopyPath } from '../canopy-path.js';
+import { listFullReason } from '../copy.js';
 import { useFieldCommentControl } from '../comments/field-comment-context.js';
 import { ExpandAllButton } from './ExpandAllButton.js';
 import { groupDescriptionProps } from './FieldDescription.js';
@@ -22,12 +23,13 @@ const ADD_SECTION = 'Add section';
  * The block templates as a menu, each with its description, so an editor picks a section by
  * what it is for. `target` is the control that opens it.
  */
-const TemplateMenu = ({ templates, onPick, onOpenChange, target }) => (_jsxs(Menu, { position: "bottom-start", withinPortal: true, shadow: "md", width: 320, onChange: onOpenChange, children: [target, _jsx(Menu.Dropdown, { "data-testid": "block-template-menu", children: _jsx(ScrollArea.Autosize, { mah: 360, type: "auto", children: templates.map((template) => (_jsxs(Menu.Item, { onClick: () => onPick(template.name), "data-testid": `block-template-${template.name}`, children: [_jsx(Text, { size: "sm", fw: 500, children: schemaLabel(template) }), template.description && (_jsx(Text, { size: "xs", c: "dimmed", style: { whiteSpace: 'normal' }, children: template.description }))] }, template.name))) }) })] }));
+const TemplateMenu = ({ templates, onPick, onOpenChange, disabled, target }) => (_jsxs(Menu, { position: "bottom-start", withinPortal: true, shadow: "md", width: 320, onChange: onOpenChange, disabled: disabled, children: [target, _jsx(Menu.Dropdown, { "data-testid": "block-template-menu", children: _jsx(ScrollArea.Autosize, { mah: 360, type: "auto", children: templates.map((template) => (_jsxs(Menu.Item, { onClick: () => onPick(template.name), "data-testid": `block-template-${template.name}`, children: [_jsx(Text, { size: "sm", fw: 500, children: schemaLabel(template) }), template.description && (_jsx(Text, { size: "xs", c: "dimmed", style: { whiteSpace: 'normal' }, children: template.description }))] }, template.name))) }) })] }));
 /**
  * The gap before a block. Its add control shows while the gap is hovered, the control is focused
  * or its menu is open, and stays in the tab order, so a keyboard reaches it before each block.
  */
-const InsertBetween = ({ templates, onPick }) => {
+const InsertBetween = ({ templates, onPick, blockedReason }) => {
+    const reasonId = useId();
     const [hovered, setHovered] = useState(false);
     const [focused, setFocused] = useState(false);
     const [opened, setOpened] = useState(false);
@@ -35,9 +37,9 @@ const InsertBetween = ({ templates, onPick }) => {
     const noHover = useMediaQuery('(hover: none)');
     const shown = hovered || focused || opened;
     const opacity = shown ? 1 : noHover ? 0.6 : 0;
-    return (_jsxs(Box, { h: 20, pos: "relative", onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), "data-testid": "block-insert-between", children: [_jsx(Box, { "aria-hidden": true, pos: "absolute", left: 0, right: 0, top: "50%", h: 2, bg: "var(--mantine-primary-color-filled)", style: { opacity: shown ? 1 : 0, transition: 'opacity 120ms ease' } }), _jsx(Group, { justify: "center", h: "100%", style: { position: 'relative' }, children: _jsx(TemplateMenu, { templates: templates, onPick: onPick, onOpenChange: setOpened, target: _jsx(Tooltip, { label: "Add section here", openDelay: 300, children: _jsx(Menu.Target, { children: _jsx(ActionIcon, { size: "sm", radius: "xl", variant: "default", "aria-label": "Add section here", onFocus: () => setFocused(true), onBlur: () => setFocused(false), style: { opacity, transition: 'opacity 120ms ease' }, children: _jsx(IconPlus, { size: 14, "aria-hidden": true }) }) }) }) }) })] }));
+    return (_jsxs(Box, { h: 20, pos: "relative", onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), "data-testid": "block-insert-between", children: [_jsx(Box, { "aria-hidden": true, pos: "absolute", left: 0, right: 0, top: "50%", h: 2, bg: "var(--mantine-primary-color-filled)", style: { opacity: shown ? 1 : 0, transition: 'opacity 120ms ease' } }), _jsx(Group, { justify: "center", h: "100%", style: { position: 'relative' }, children: _jsx(TemplateMenu, { templates: templates, onPick: onPick, onOpenChange: setOpened, disabled: !!blockedReason, target: _jsx(Tooltip, { label: blockedReason ?? 'Add section here', openDelay: 300, multiline: !!blockedReason, maw: 280, children: _jsx(Menu.Target, { children: _jsxs(ActionIcon, { size: "sm", radius: "xl", variant: "default", "aria-label": "Add section here", "aria-disabled": blockedReason ? true : undefined, "aria-describedby": blockedReason ? reasonId : undefined, "data-disabled": blockedReason ? true : undefined, onFocus: () => setFocused(true), onBlur: () => setFocused(false), style: { opacity, transition: 'opacity 120ms ease' }, children: [_jsx(IconPlus, { size: 14, "aria-hidden": true }), blockedReason && (_jsx(VisuallyHidden, { component: "span", id: reasonId, children: blockedReason }))] }) }) }) }) })] }));
 };
-export const BlockField = ({ label, required, description, templates, value, onChange, renderField, path, dataCanopyField, readOnly = false, resetKey = '', hasErrors, onRemoved, }) => {
+export const BlockField = ({ label, required, description, templates, value, onChange, renderField, path, dataCanopyField, readOnly = false, resetKey = '', hasErrors, onRemoved, maxItems, }) => {
     const descriptionBaseId = useId();
     const commentControl = useFieldCommentControl(dataCanopyField ?? formatCanopyPath(path));
     const keysFor = useListItemKeys();
@@ -48,7 +50,12 @@ export const BlockField = ({ label, required, description, templates, value, onC
         if (!readOnly)
             onChange(next);
     };
+    const fullReason = maxItems !== undefined && value.length >= maxItems
+        ? listFullReason(maxItems, 'section', 'sections')
+        : undefined;
     const insertAt = (index, block) => {
+        if (fullReason)
+            return;
         focusAfterRenderRef.current = index;
         emit([...value.slice(0, index), block, ...value.slice(index)]);
     };
@@ -81,7 +88,7 @@ export const BlockField = ({ label, required, description, templates, value, onC
                         ...value.slice(0, idx + 1),
                         withFreshItemKeys({ type: 'block', name: 'blocks', templates }, structuredClone(value[idx])),
                         ...value.slice(idx + 1),
-                    ]), onRemove: (idx) => {
+                    ]), duplicateBlockedReason: fullReason, onRemove: (idx) => {
                         if (readOnly)
                             return;
                         const block = value[idx];
@@ -89,7 +96,7 @@ export const BlockField = ({ label, required, description, templates, value, onC
                         onRemoved?.(idx, block);
                     }, renderBetween: readOnly
                         ? undefined
-                        : (idx) => _jsx(InsertBetween, { templates: templates, onPick: addAt(idx) }), renderItem: (block, idx) => {
+                        : (idx) => (_jsx(InsertBetween, { templates: templates, onPick: addAt(idx), blockedReason: fullReason })), renderItem: (block, idx) => {
                         const template = findTemplate(templates, block.template);
                         const currentPath = [...path, idx];
                         if (!template) {
@@ -99,5 +106,5 @@ export const BlockField = ({ label, required, description, templates, value, onC
                                 ...(isPlainRecord(block.value) ? block.value : {}),
                                 [f.name]: next,
                             }), [...currentPath, f.name]) }, f.name)));
-                    } }), value.length === 0 && (_jsx(Text, { size: "sm", c: "dimmed", children: readOnly ? 'No sections.' : 'No sections yet.' })), !readOnly && (_jsx(Group, { children: _jsx(TemplateMenu, { templates: templates, onPick: addAt(value.length), target: _jsx(Menu.Target, { children: _jsx(Button, { variant: "light", size: "xs", leftSection: _jsx(IconPlus, { size: 14, "aria-hidden": true }), "data-testid": "block-add-section", children: ADD_SECTION }) }) }) }))] }) }));
+                    } }), value.length === 0 && (_jsx(Text, { size: "sm", c: "dimmed", children: readOnly ? 'No sections.' : 'No sections yet.' })), !readOnly && (_jsx(Group, { children: _jsx(TemplateMenu, { templates: templates, onPick: addAt(value.length), disabled: !!fullReason, target: _jsx(Tooltip, { label: fullReason, disabled: !fullReason, multiline: true, maw: 280, children: _jsx(Menu.Target, { children: _jsx(Button, { variant: "light", size: "xs", leftSection: _jsx(IconPlus, { size: 14, "aria-hidden": true }), "data-disabled": fullReason ? true : undefined, "aria-disabled": fullReason ? true : undefined, "data-testid": "block-add-section", children: ADD_SECTION }) }) }) }) }))] }) }));
 };

package/dist/editor/fields/ItemList.d.ts

@@ -1,9 +1,17 @@
 import React from 'react';
+import { type MantineColor } from '@mantine/core';
 import type { ItemExpansion } from './item-expansion.js';
 /** What a collapsed row shows: its title, and a second value from its content. */
 interface ItemSummary {
     title: string;
     secondary?: string;
+    /** A status shown after the title, in its colour's light variant; part of the row's name. */
+    badge?: {
+        label: string;
+        color: MantineColor;
+    };
+    /** The title is still loading: the row shows a placeholder in its place. */
+    pending?: boolean;
 }
 export interface ItemListProps<T> {
     items: readonly T[];
@@ -20,7 +28,10 @@ export interface ItemListProps<T> {
     /** True when a field inside row `index` has a validation error. */
     hasErrors?: (index: number) => boolean;
     onMove: (from: number, to: number) => void;
-    onDuplicate: (index: number) => void;
+    /** Without it, the row menu offers no Duplicate. */
+    onDuplicate?: (index: number) => void;
+    /** Why Duplicate can't act now, such as a list at its `maxItems`; shown in its place. */
+    duplicateBlockedReason?: string;
     /** Takes row `index` out; focus has already moved to the enclosing `[data-removal-focus]` list. */
     onRemove: (index: number) => void;
     /** Rendered before row `index`, such as a block list's insert-here control. */
@@ -30,13 +41,20 @@ export interface ItemListProps<T> {
      * Cleared once used.
      */
     focusAfterRenderRef?: React.MutableRefObject<number | null>;
+    /**
+     * Said through the list's live region, by a caller whose own control keeps focus when it adds a
+     * row. Pass a new object for each announcement.
+     */
+    announcement?: {
+        message: string;
+    };
     'data-testid'?: string;
 }
 /**
  * The rows of an object list or block list: each collapses to a one-line summary and carries a
  * drag handle (pointer and keyboard, via dnd-kit) and a "…" menu with Move up, Move down,
- * Duplicate and Remove. A read-only list keeps only collapsing. A collapsed row stays mounted
+ * Duplicate (when the list offers it) and Remove. A read-only list keeps only collapsing. A collapsed row stays mounted
  * and opens when something asks to reveal a field inside it (`REVEAL_FIELD_EVENT`).
  */
-export declare function ItemList<T>({ items, itemKeys, path, readOnly, expansion, summarize, renderItem, describe, hasErrors, onMove, onDuplicate, onRemove, renderBetween, focusAfterRenderRef, 'data-testid': testId, }: ItemListProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function ItemList<T>({ items, itemKeys, path, readOnly, expansion, summarize, renderItem, describe, hasErrors, onMove, onDuplicate, onRemove, renderBetween, focusAfterRenderRef, announcement: callerAnnouncement, duplicateBlockedReason, 'data-testid': testId, }: ItemListProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/editor/fields/ItemList.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useEffect, useId, useRef, useState } from 'react';
-import { ActionIcon, Box, Group, Menu, Paper, Stack, Text, Tooltip, UnstyledButton, VisuallyHidden, } from '@mantine/core';
+import { ActionIcon, Badge, Box, Group, Menu, Paper, Skeleton, Stack, Text, Tooltip, UnstyledButton, VisuallyHidden, } from '@mantine/core';
 import { DndContext, closestCenter, KeyboardSensor, PointerSensor, useSensor, useSensors, } from '@dnd-kit/core';
 import { SortableContext, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy, } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
@@ -17,10 +17,10 @@ const ROW_GAP = 8;
 /**
  * The rows of an object list or block list: each collapses to a one-line summary and carries a
  * drag handle (pointer and keyboard, via dnd-kit) and a "…" menu with Move up, Move down,
- * Duplicate and Remove. A read-only list keeps only collapsing. A collapsed row stays mounted
+ * Duplicate (when the list offers it) and Remove. A read-only list keeps only collapsing. A collapsed row stays mounted
  * and opens when something asks to reveal a field inside it (`REVEAL_FIELD_EVENT`).
  */
-export function ItemList({ items, itemKeys, path, readOnly, expansion, summarize, renderItem, describe, hasErrors, onMove, onDuplicate, onRemove, renderBetween, focusAfterRenderRef, 'data-testid': testId, }) {
+export function ItemList({ items, itemKeys, path, readOnly, expansion, summarize, renderItem, describe, hasErrors, onMove, onDuplicate, onRemove, renderBetween, focusAfterRenderRef, announcement: callerAnnouncement, duplicateBlockedReason, 'data-testid': testId, }) {
     const listRef = useRef(null);
     const [announcement, setAnnouncement] = useState('');
     // Constant: DndContext's hooks depend on the sensor count; read-only disables each row instead.
@@ -36,6 +36,12 @@ export function ItemList({ items, itemKeys, path, readOnly, expansion, summarize
         if (row)
             focusFieldTarget(row);
     });
+    const [lastCallerAnnouncement, setLastCallerAnnouncement] = useState(callerAnnouncement);
+    if (callerAnnouncement !== lastCallerAnnouncement) {
+        setLastCallerAnnouncement(callerAnnouncement);
+        if (callerAnnouncement)
+            setAnnouncement(callerAnnouncement.message);
+    }
     const titleAt = (index) => summarize(items[index], index).title;
     const indexOf = (id) => itemKeys.indexOf(String(id));
     const position = (index) => `position ${index + 1} of ${items.length}`;
@@ -63,7 +69,7 @@ export function ItemList({ items, itemKeys, path, readOnly, expansion, summarize
         setAnnouncement(`${titleAt(from)} moved to ${position(to)}.`);
     };
     const duplicate = (index) => {
-        onDuplicate(index);
+        onDuplicate?.(index);
         setAnnouncement(`${titleAt(index)} duplicated, position ${index + 2} of ${items.length + 1}.`);
     };
     const remove = (index) => {
@@ -74,10 +80,10 @@ export function ItemList({ items, itemKeys, path, readOnly, expansion, summarize
     return (_jsxs("div", { ref: listRef, "data-item-list": true, "data-testid": testId, children: [_jsx(DndContext, { sensors: sensors, collisionDetection: closestCenter, onDragEnd: handleDragEnd, accessibility: { announcements }, children: _jsx(SortableContext, { items: [...itemKeys], strategy: verticalListSortingStrategy, children: items.map((item, idx) => {
                         const key = itemKeys[idx];
                         const summary = summarize(item, idx);
-                        return (_jsxs(React.Fragment, { children: [renderBetween ? renderBetween(idx) : idx > 0 && _jsx(Box, { h: ROW_GAP, "aria-hidden": true }), _jsx(ItemRow, { rowKey: key, canopyPath: formatCanopyPath([...path, idx]), summary: summary, description: describe?.(item), hasErrors: hasErrors?.(idx) ?? false, expanded: expansion.isExpanded(key), onExpandedChange: (open) => expansion.setExpanded(key, open), readOnly: readOnly, isFirst: idx === 0, isLast: idx === items.length - 1, onMoveUp: () => move(idx, idx - 1), onMoveDown: () => move(idx, idx + 1), onDuplicate: () => duplicate(idx), onRemove: () => remove(idx), children: renderItem(item, idx) })] }, key));
+                        return (_jsxs(React.Fragment, { children: [renderBetween ? renderBetween(idx) : idx > 0 && _jsx(Box, { h: ROW_GAP, "aria-hidden": true }), _jsx(ItemRow, { rowKey: key, canopyPath: formatCanopyPath([...path, idx]), summary: summary, description: describe?.(item), hasErrors: hasErrors?.(idx) ?? false, expanded: expansion.isExpanded(key), onExpandedChange: (open) => expansion.setExpanded(key, open), readOnly: readOnly, isFirst: idx === 0, isLast: idx === items.length - 1, onMoveUp: () => move(idx, idx - 1), onMoveDown: () => move(idx, idx + 1), onDuplicate: onDuplicate ? () => duplicate(idx) : undefined, duplicateBlockedReason: duplicateBlockedReason, onRemove: () => remove(idx), children: renderItem(item, idx) })] }, key));
                     }) }) }), _jsx(VisuallyHidden, { "aria-live": "polite", children: announcement })] }));
 }
-const ItemRow = ({ rowKey, canopyPath, summary, description, hasErrors, expanded, onExpandedChange, readOnly, isFirst, isLast, onMoveUp, onMoveDown, onDuplicate, onRemove, children, }) => {
+const ItemRow = ({ rowKey, canopyPath, summary, description, hasErrors, expanded, onExpandedChange, readOnly, isFirst, isLast, onMoveUp, onMoveDown, onDuplicate, duplicateBlockedReason, onRemove, children, }) => {
     const baseId = useId();
     const bodyId = `${baseId}-body`;
     const rowRef = useRef(null);
@@ -111,7 +117,7 @@ const ItemRow = ({ rowKey, canopyPath, summary, description, hasErrors, expanded
         requestAnimationFrame(() => menuTargetRef.current?.focus());
     };
     // Rows can share a title (two sections of one template), so names carry the second value too.
-    const name = summary.secondary ? `${summary.title}, ${summary.secondary}` : summary.title;
+    const name = [summary.title, summary.secondary, summary.badge?.label].filter(Boolean).join(', ');
     const actionsLabel = `Actions for ${name}`;
     return (_jsxs(Paper, { ref: (node) => {
             rowRef.current = node;
@@ -126,5 +132,7 @@ const ItemRow = ({ rowKey, canopyPath, summary, description, hasErrors, expanded
                                         flexShrink: 0,
                                         transform: expanded ? 'rotate(90deg)' : undefined,
                                         transition: 'transform 120ms ease',
-                                    } }), _jsx(Text, { size: "sm", fw: 500, truncate: "end", style: summary.secondary ? { flexShrink: 0, maxWidth: '60%' } : { minWidth: 0 }, children: summary.title }), summary.secondary && (_jsx(Text, { size: "sm", c: "dimmed", truncate: "end", style: { minWidth: 0 }, children: summary.secondary })), hasErrors && !expanded && (_jsxs(Group, { gap: 2, wrap: "nowrap", ml: "auto", style: { flexShrink: 0 }, children: [_jsx(IconAlertCircle, { size: 14, color: "var(--canopy-danger-text)", "aria-hidden": true }), _jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: "Has errors" })] }))] }) }), !readOnly && (_jsxs(Menu, { position: "bottom-end", withinPortal: true, shadow: "sm", width: 220, children: [_jsx(Tooltip, { label: actionsLabel, openDelay: 500, children: _jsx(Menu.Target, { children: _jsx(ActionIcon, { ref: menuTargetRef, variant: "subtle", color: "gray", "aria-label": actionsLabel, "data-testid": "item-row-menu", children: _jsx(IconDots, { size: 16, "aria-hidden": true }) }) }) }), _jsxs(Menu.Dropdown, { children: [_jsx(ReasonedMenuItem, { blockedReason: isFirst ? 'Already first' : undefined, onClick: thenFocusMenu(onMoveUp), "data-testid": "item-row-move-up", children: "Move up" }), _jsx(ReasonedMenuItem, { blockedReason: isLast ? 'Already last' : undefined, onClick: thenFocusMenu(onMoveDown), "data-testid": "item-row-move-down", children: "Move down" }), _jsx(Menu.Item, { onClick: thenFocusMenu(onDuplicate), "data-testid": "item-row-duplicate", children: "Duplicate" }), _jsx(Menu.Divider, {}), _jsx(DestructiveMenuItem, { onClick: onRemove, "data-testid": "item-row-remove", children: EDITOR_ACTIONS.remove })] })] }))] }), _jsx(Box, { id: bodyId, hidden: !expanded, children: _jsxs(Stack, { gap: "sm", px: "sm", pb: "sm", pt: 4, children: [description && _jsx(FieldDescription, { baseId: baseId, description: description }), children] }) })] }));
+                                    } }), summary.pending ? (
+                                // About the height of the title's line, which replaces it.
+                                _jsx(Skeleton, { height: 14, width: "40%", my: 3, "data-testid": "item-row-title-pending" })) : (_jsx(Text, { size: "sm", fw: 500, truncate: "end", style: summary.secondary ? { flexShrink: 0, maxWidth: '60%' } : { minWidth: 0 }, children: summary.title })), summary.secondary && (_jsx(Text, { size: "sm", c: "dimmed", truncate: "end", style: { minWidth: 0 }, children: summary.secondary })), summary.badge && !summary.pending && (_jsx(Badge, { variant: "light", color: summary.badge.color, size: "sm", tt: "none", style: { flexShrink: 0 }, children: summary.badge.label })), hasErrors && !expanded && (_jsxs(Group, { gap: 2, wrap: "nowrap", ml: "auto", style: { flexShrink: 0 }, children: [_jsx(IconAlertCircle, { size: 14, color: "var(--canopy-danger-text)", "aria-hidden": true }), _jsx(Text, { size: "xs", c: "var(--canopy-danger-text)", children: "Has errors" })] }))] }) }), !readOnly && (_jsxs(Menu, { position: "bottom-end", withinPortal: true, shadow: "sm", width: 220, children: [_jsx(Tooltip, { label: actionsLabel, openDelay: 500, children: _jsx(Menu.Target, { children: _jsx(ActionIcon, { ref: menuTargetRef, variant: "subtle", color: "gray", "aria-label": actionsLabel, "data-testid": "item-row-menu", children: _jsx(IconDots, { size: 16, "aria-hidden": true }) }) }) }), _jsxs(Menu.Dropdown, { children: [_jsx(ReasonedMenuItem, { blockedReason: isFirst ? 'Already first' : undefined, onClick: thenFocusMenu(onMoveUp), "data-testid": "item-row-move-up", children: "Move up" }), _jsx(ReasonedMenuItem, { blockedReason: isLast ? 'Already last' : undefined, onClick: thenFocusMenu(onMoveDown), "data-testid": "item-row-move-down", children: "Move down" }), onDuplicate && (_jsx(ReasonedMenuItem, { blockedReason: duplicateBlockedReason, onClick: thenFocusMenu(onDuplicate), "data-testid": "item-row-duplicate", children: "Duplicate" })), _jsx(Menu.Divider, {}), _jsx(DestructiveMenuItem, { onClick: onRemove, "data-testid": "item-row-remove", children: EDITOR_ACTIONS.remove })] })] }))] }), _jsx(Box, { id: bodyId, hidden: !expanded, children: _jsxs(Stack, { gap: "sm", px: "sm", pb: "sm", pt: 4, children: [description && _jsx(FieldDescription, { baseId: baseId, description: description }), children] }) })] }));
 };

package/dist/editor/fields/NumberListField.d.ts

@@ -8,6 +8,8 @@ export interface NumberListFieldProps {
     dataCanopyField?: string;
     /** Shows the value without accepting edits. */
     readOnly?: boolean;
+    /** The most items the list holds; at or over it, nothing adds and the hint says why. */
+    maxItems?: number;
 }
 /**
  * Editor for `type: 'number', list: true` fields.

package/dist/editor/fields/NumberListField.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useId, useState } from 'react';
 import { TagsInput } from '@mantine/core';
+import { listFullReason } from '../copy.js';
 import { LabelledInput } from './FieldLabel.js';
+import { tagCap, withHint } from './StringListField.js';
 /**
  * A tag is a number only if it is non-blank AND parses finitely.
  *
@@ -28,11 +30,13 @@ const parseTag = (tag) => {
  * on Enter indistinguishably from being accepted, with nothing to tell a
  * typo from a broken field — so rejected text is named in the error slot.
  */
-export const NumberListField = ({ id, label, description, value, onChange, dataCanopyField, readOnly = false, }) => {
+export const NumberListField = ({ id, label, description, value, onChange, dataCanopyField, readOnly = false, maxItems, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const [rejected, setRejected] = useState([]);
-    return (_jsx(LabelledInput, { label: label, inputId: inputId, canopyPath: dataCanopyField, children: _jsx(TagsInput, { id: inputId, description: description, value: value.map(String), size: "sm", error: rejected.length > 0
+    return (_jsx(LabelledInput, { label: label, inputId: inputId, canopyPath: dataCanopyField, children: _jsx(TagsInput, { id: inputId, description: !readOnly && maxItems !== undefined && value.length >= maxItems
+                ? withHint(description, listFullReason(maxItems))
+                : description, maxTags: tagCap(value.length, maxItems), value: value.map(String), size: "sm", error: rejected.length > 0
                 ? `Not ${rejected.length === 1 ? 'a number' : 'numbers'}: ${rejected.join(', ')}`
                 : undefined, readOnly: readOnly, onChange: (next) => {
                 if (readOnly)

package/dist/editor/fields/ObjectListField.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef } from 'react';
-import { Button, Group, Paper, Stack, Text } from '@mantine/core';
+import { Button, Group, Paper, Stack, Text, Tooltip } from '@mantine/core';
 import { IconPlus } from '@tabler/icons-react';
 import { isPlainRecord } from '../../validation/field-traversal.js';
 import { ITEM_KEY, mintItemKey, withFreshItemKeys } from '../../item-keys.js';
 import { formatCanopyPath } from '../canopy-path.js';
+import { listFullReason } from '../copy.js';
 import { useFieldCommentControl } from '../comments/field-comment-context.js';
 import { groupDescriptionProps } from './FieldDescription.js';
 import { FieldLabel } from './FieldLabel.js';
@@ -20,7 +21,12 @@ export const ObjectListField = ({ id, label, field, items, itemKeys, onChange, r
     const commentControl = useFieldCommentControl(canopyPath);
     const expansion = useItemExpansion(itemKeys, resetKey);
     const focusAfterRenderRef = useRef(null);
+    const fullReason = field.maxItems !== undefined && items.length >= field.maxItems
+        ? listFullReason(field.maxItems)
+        : undefined;
     const insertAt = (index, item) => {
+        if (fullReason)
+            return;
         focusAfterRenderRef.current = index;
         onChange([...items.slice(0, index), item, ...items.slice(index)]);
     };
@@ -38,7 +44,7 @@ export const ObjectListField = ({ id, label, field, items, itemKeys, onChange, r
                         ...items.slice(0, idx + 1),
                         withFreshItemKeys(field, structuredClone(items[idx])),
                         ...items.slice(idx + 1),
-                    ]), onRemove: (idx) => {
+                    ]), duplicateBlockedReason: fullReason, onRemove: (idx) => {
                         const item = items[idx];
                         onChange(items.filter((_, i) => i !== idx));
                         onRemoved?.(idx, item);
@@ -53,5 +59,5 @@ export const ObjectListField = ({ id, label, field, items, itemKeys, onChange, r
                                     onChange(nextItems);
                                 }, childPath) }, formatCanopyPath(childPath)));
                         });
-                    } }), items.length === 0 && (_jsx(Text, { size: "sm", c: "dimmed", children: readOnly ? 'Nothing added.' : 'Nothing added yet.' })), !readOnly && (_jsx(Group, { children: _jsxs(Button, { variant: "light", size: "xs", leftSection: _jsx(IconPlus, { size: 14, "aria-hidden": true }), onClick: () => insertAt(items.length, { [ITEM_KEY]: mintItemKey() }), "data-testid": "object-list-add", children: ["Add ", field.itemLabel ?? 'item'] }) }))] }) }));
+                    } }), items.length === 0 && (_jsx(Text, { size: "sm", c: "dimmed", children: readOnly ? 'Nothing added.' : 'Nothing added yet.' })), !readOnly && (_jsx(Group, { children: _jsx(Tooltip, { label: fullReason, disabled: !fullReason, multiline: true, maw: 280, children: _jsxs(Button, { variant: "light", size: "xs", leftSection: _jsx(IconPlus, { size: 14, "aria-hidden": true }), onClick: () => insertAt(items.length, { [ITEM_KEY]: mintItemKey() }), "data-disabled": fullReason ? true : undefined, "aria-disabled": fullReason ? true : undefined, "data-testid": "object-list-add", children: ["Add ", field.itemLabel ?? 'item'] }) }) }))] }) }));
 };

package/dist/editor/fields/ReferenceField.d.ts

@@ -1,9 +1,8 @@
 import React from 'react';
+import type { ReferenceOptionSort } from '../../config/index.js';
+import { type ReferenceOption } from './use-reference-options.js';
 /** @internal Exported for tests. */
-export interface ReferenceOption {
-    value: string;
-    label: string;
-}
+export type { ReferenceOption };
 export interface ReferenceFieldProps {
     id?: string;
     label?: string;
@@ -13,9 +12,9 @@ export interface ReferenceFieldProps {
     entryTypes?: string[];
     displayField?: string;
     branch?: string;
-    value: string | string[];
-    onChange: (value: string | string[]) => void;
-    multiple?: boolean;
+    optionSort?: ReferenceOptionSort;
+    value: unknown;
+    onChange: (value: string) => void;
     dataCanopyField?: string;
     /** Shows the value without accepting edits. */
     readOnly?: boolean;