canopycms 0.4.0 → 0.5.0

package/dist/cli/init.js

@@ -160,7 +160,7 @@ var init_mdx_allowlist = __esm({
 
 // dist/config/schemas/field.js
 import { z } from "zod";
-var fieldBaseSchema, selectOptionSchema, referenceOptionSchema, primitiveFieldSchema, mdxPropAllowSchema, mdxAllowlistSchema, markdownFieldSchema, ASPECT_RATIO_RE, imageFieldSchema, selectFieldSchema, referenceFieldSchema, fieldHolder, blockSchema, blockFieldSchema, objectFieldSchema, inlineGroupFieldSchema, customFieldSchema, knownFieldSchema, fieldSchema;
+var fieldBaseSchema, selectOptionSchema, referenceOptionSchema, primitiveFieldSchema, mdxPropAllowSchema, mdxAllowlistSchema, markdownFieldSchema, ASPECT_RATIO_RE, imageFieldSchema, selectFieldSchema, referenceSortFieldSchema, referenceFieldSchema, fieldHolder, blockSchema, blockFieldSchema, objectFieldSchema, inlineGroupFieldSchema, customFieldSchema, knownFieldSchema, fieldSchema;
 var init_field = __esm({
   "dist/config/schemas/field.js"() {
     "use strict";
@@ -173,7 +173,10 @@ var init_field = __esm({
       required: z.boolean().optional(),
       list: z.boolean().optional(),
       isTitle: z.boolean().optional(),
-      isBody: z.boolean().optional()
+      isBody: z.boolean().optional(),
+      // Listed so a parse keeps it (zod strips unknown keys); which fields may carry it is
+      // `ensureMaxItemsPlacement`'s call (config/validation.ts).
+      maxItems: z.number().int().positive().optional()
     });
     selectOptionSchema = z.union([
       z.string(),
@@ -231,6 +234,7 @@ var init_field = __esm({
       type: z.literal("select"),
       options: z.array(selectOptionSchema).min(1)
     });
+    referenceSortFieldSchema = z.string().regex(/^[^.]+(\.[^.]+)*$/, 'must be a field name or a dotted path such as "meta.publishedAt"');
     referenceFieldSchema = fieldBaseSchema.extend({
       type: z.literal("reference"),
       collections: z.array(z.string().min(1)).min(1).optional(),
@@ -241,7 +245,14 @@ var init_field = __esm({
       // default, so a consumer that adopts this schema's parse output would silently delete a
       // runtime-consumed flag and the feature would no-op with no error. (`resolvedSchema` is
       // absent on purpose — it is type-inference-only and stripping it changes no behavior.)
-      includeBody: z.boolean().optional()
+      includeBody: z.boolean().optional(),
+      optionSort: z.union([
+        z.enum(["label", "collection"]),
+        z.object({
+          field: referenceSortFieldSchema,
+          direction: z.enum(["asc", "desc"]).optional()
+        }).strict()
+      ]).optional()
     });
     fieldHolder = [z.never()];
     blockSchema = z.object({
@@ -439,7 +450,7 @@ var init_media = __esm({
 
 // dist/config/schemas/config.js
 import { z as z5 } from "zod";
-var defaultBranchAccessSchema, defaultPathAccessLevelSchema, defaultPathAccessLevelsSchema, defaultPathAccessSchema, defaultBaseBranchSchema, defaultRemoteNameSchema, defaultRemoteUrlSchema, gitBotAuthorNameSchema, gitBotAuthorEmailSchema, githubTokenEnvVarSchema, operatingModeSchema, deployedAsSchema, contentRootSchema, sourceRootSchema, basePathSchema, deploymentNameSchema, devContentSyncSchema, devConfigSchema, editorConfigSchema, CanopyConfigSchema, DEFAULT_PROD_WORKSPACE;
+var defaultBranchAccessSchema, defaultPathAccessLevelSchema, defaultPathAccessLevelsSchema, defaultPathAccessSchema, defaultBaseBranchSchema, defaultRemoteNameSchema, defaultRemoteUrlSchema, gitBotAuthorNameSchema, gitBotAuthorEmailSchema, githubTokenEnvVarSchema, operatingModeSchema, deployedAsSchema, contentRootSchema, sourceRootSchema, basePathSchema, deploymentNameSchema, devContentSyncSchema, devConfigSchema, editorConfigSchema, seoFieldNameSchema, seoSchema, CanopyConfigSchema, DEFAULT_PROD_WORKSPACE;
 var init_config = __esm({
   "dist/config/schemas/config.js"() {
     "use strict";
@@ -486,6 +497,19 @@ var init_config = __esm({
       // Optional: provider sign-in UI for signed-out users (see EditorSignInProps)
       SignInComponent: z5.custom().optional()
     });
+    seoFieldNameSchema = z5.string().min(1).optional();
+    seoSchema = z5.object({
+      group: z5.string().min(1).optional(),
+      fields: z5.object({
+        title: seoFieldNameSchema,
+        description: seoFieldNameSchema,
+        ogImage: seoFieldNameSchema,
+        ogType: seoFieldNameSchema,
+        canonical: seoFieldNameSchema,
+        noindex: seoFieldNameSchema,
+        twitterCard: seoFieldNameSchema
+      }).strict().optional()
+    }).strict();
     CanopyConfigSchema = z5.object({
       media: mediaSchema.optional(),
       // No outer .optional(): both schemas already .default('deny'), so the field is optional on
@@ -535,6 +559,7 @@ var init_config = __esm({
       entryLinkUrl: z5.custom().optional(),
       validateEntry: z5.custom().optional(),
       mdxAllow: mdxAllowlistSchema.optional(),
+      seo: seoSchema.optional(),
       dev: devConfigSchema.optional()
     }).strict();
     DEFAULT_PROD_WORKSPACE = "/mnt/efs";

package/dist/config/index.d.ts

@@ -8,7 +8,7 @@
  * import { defineCanopyConfig, type FieldConfig } from 'canopycms'
  * ```
  */
-export type { PrimitiveFieldType, FieldType, ContentFormat, MediaAdapterKind, PermissionLevel, PermissionTarget, PathPermission, SelectOption, ReferenceOption, FieldConfig, BlockConfig, BlockFieldConfig, SelectFieldConfig, ReferenceFieldConfig, ImageFieldConfig, MarkdownFieldConfig, MdxAllowlist, MdxComponentAllow, MdxPropAllow, ImageFieldValue, ObjectFieldConfig, InlineGroupFieldConfig, CustomFieldConfig, EntrySchema, BranchSchema, EntryTypeConfig, EntryTypeUnavailable, CollectionConfig, RootCollectionConfig, MediaConfig, CanopyEditorConfig, DefaultBranchAccess, DefaultPathAccess, DefaultPathAccessLevel, DefaultPathAccessLevels, DefaultBaseBranch, DefaultRemoteName, DefaultRemoteUrl, GitBotAuthorName, GitBotAuthorEmail, GithubTokenEnvVar, CanopyOperatingMode, ContentRoot, SourceRoot, CanopyConfig, CanopyConfigInput, CanopyConfigFragment, FlatSchemaItem, CanopyClientConfig, ClientOnlyFields, EditorSignInProps, EntryValidationIssue, ValidateEntryInput, ValidateEntryHook, } from './types.js';
+export type { PrimitiveFieldType, FieldType, ContentFormat, MediaAdapterKind, PermissionLevel, PermissionTarget, PathPermission, SelectOption, ReferenceOption, FieldConfig, BlockConfig, BlockFieldConfig, SelectFieldConfig, ReferenceFieldConfig, ReferenceOptionSort, ImageFieldConfig, MarkdownFieldConfig, MdxAllowlist, MdxComponentAllow, MdxPropAllow, ImageFieldValue, ObjectFieldConfig, InlineGroupFieldConfig, CustomFieldConfig, EntrySchema, BranchSchema, EntryTypeConfig, EntryTypeUnavailable, CollectionConfig, RootCollectionConfig, MediaConfig, CanopyEditorConfig, DefaultBranchAccess, DefaultPathAccess, DefaultPathAccessLevel, DefaultPathAccessLevels, DefaultBaseBranch, DefaultRemoteName, DefaultRemoteUrl, GitBotAuthorName, GitBotAuthorEmail, GithubTokenEnvVar, CanopyOperatingMode, ContentRoot, SourceRoot, CanopyConfig, CanopyConfigInput, CanopyConfigFragment, FlatSchemaItem, CanopyClientConfig, ClientOnlyFields, EditorSignInProps, EntryValidationIssue, ValidateEntryInput, ValidateEntryHook, } from './types.js';
 export { primitiveFieldTypes, fieldTypes } from './types.js';
 export { CanopyConfigSchema, getConfigDefaults, DEFAULT_PROD_WORKSPACE } from './schemas/config.js';
 export { fieldSchema, blockSchema, selectOptionSchema, referenceOptionSchema, imageFieldSchema, } from './schemas/field.js';

package/dist/config/schemas/config.d.ts

@@ -105,6 +105,56 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     entryLinkUrl: z.ZodOptional<z.ZodType<EntryLinkUrlResolver, z.ZodTypeDef, EntryLinkUrlResolver>>;
     validateEntry: z.ZodOptional<z.ZodType<ValidateEntryHook, z.ZodTypeDef, ValidateEntryHook>>;
     mdxAllow: z.ZodOptional<z.ZodType<import("../index.js").MdxAllowlist, z.ZodTypeDef, import("../index.js").MdxAllowlist>>;
+    seo: z.ZodOptional<z.ZodObject<{
+        group: z.ZodOptional<z.ZodString>;
+        fields: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            ogImage: z.ZodOptional<z.ZodString>;
+            ogType: z.ZodOptional<z.ZodString>;
+            canonical: z.ZodOptional<z.ZodString>;
+            noindex: z.ZodOptional<z.ZodString>;
+            twitterCard: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            description?: string | undefined;
+            title?: string | undefined;
+            ogImage?: string | undefined;
+            ogType?: string | undefined;
+            canonical?: string | undefined;
+            noindex?: string | undefined;
+            twitterCard?: string | undefined;
+        }, {
+            description?: string | undefined;
+            title?: string | undefined;
+            ogImage?: string | undefined;
+            ogType?: string | undefined;
+            canonical?: string | undefined;
+            noindex?: string | undefined;
+            twitterCard?: string | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        fields?: {
+            description?: string | undefined;
+            title?: string | undefined;
+            ogImage?: string | undefined;
+            ogType?: string | undefined;
+            canonical?: string | undefined;
+            noindex?: string | undefined;
+            twitterCard?: string | undefined;
+        } | undefined;
+        group?: string | undefined;
+    }, {
+        fields?: {
+            description?: string | undefined;
+            title?: string | undefined;
+            ogImage?: string | undefined;
+            ogType?: string | undefined;
+            canonical?: string | undefined;
+            noindex?: string | undefined;
+            twitterCard?: string | undefined;
+        } | undefined;
+        group?: string | undefined;
+    }>>;
     dev: z.ZodOptional<z.ZodObject<{
         contentSync: z.ZodOptional<z.ZodDefault<z.ZodEnum<["off", "warn"]>>>;
     }, "strip", z.ZodTypeAny, {
@@ -167,6 +217,18 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     entryLinkUrl?: EntryLinkUrlResolver | undefined;
     validateEntry?: ValidateEntryHook | undefined;
     mdxAllow?: import("../index.js").MdxAllowlist | undefined;
+    seo?: {
+        fields?: {
+            description?: string | undefined;
+            title?: string | undefined;
+            ogImage?: string | undefined;
+            ogType?: string | undefined;
+            canonical?: string | undefined;
+            noindex?: string | undefined;
+            twitterCard?: string | undefined;
+        } | undefined;
+        group?: string | undefined;
+    } | undefined;
 }, {
     gitBotAuthorName: string;
     gitBotAuthorEmail: string;
@@ -222,6 +284,18 @@ export declare const CanopyConfigSchema: z.ZodObject<{
     entryLinkUrl?: EntryLinkUrlResolver | undefined;
     validateEntry?: ValidateEntryHook | undefined;
     mdxAllow?: import("../index.js").MdxAllowlist | undefined;
+    seo?: {
+        fields?: {
+            description?: string | undefined;
+            title?: string | undefined;
+            ogImage?: string | undefined;
+            ogType?: string | undefined;
+            canonical?: string | undefined;
+            noindex?: string | undefined;
+            twitterCard?: string | undefined;
+        } | undefined;
+        group?: string | undefined;
+    } | undefined;
 }>;
 /**
  * Default workspace path for prod mode (used when CANOPYCMS_WORKSPACE_ROOT is not set): where

package/dist/config/schemas/config.js

@@ -61,6 +61,26 @@ const editorConfigSchema = z.object({
     // Optional: provider sign-in UI for signed-out users (see EditorSignInProps)
     SignInComponent: z.custom().optional(),
 });
+const seoFieldNameSchema = z.string().min(1).optional();
+// Strict, so a misspelled key (`noIndex`) fails the parse instead of leaving every surface
+// reading the default field name.
+const seoSchema = z
+    .object({
+    group: z.string().min(1).optional(),
+    fields: z
+        .object({
+        title: seoFieldNameSchema,
+        description: seoFieldNameSchema,
+        ogImage: seoFieldNameSchema,
+        ogType: seoFieldNameSchema,
+        canonical: seoFieldNameSchema,
+        noindex: seoFieldNameSchema,
+        twitterCard: seoFieldNameSchema,
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
 export const CanopyConfigSchema = z
     .object({
     media: mediaSchema.optional(),
@@ -110,6 +130,7 @@ export const CanopyConfigSchema = z
     entryLinkUrl: z.custom().optional(),
     validateEntry: z.custom().optional(),
     mdxAllow: mdxAllowlistSchema.optional(),
+    seo: seoSchema.optional(),
     dev: devConfigSchema.optional(),
 })
     .strict();

package/dist/config/schemas/field.d.ts

@@ -33,6 +33,7 @@ export declare const imageFieldSchema: z.ZodObject<{
     list: z.ZodOptional<z.ZodBoolean>;
     isTitle: z.ZodOptional<z.ZodBoolean>;
     isBody: z.ZodOptional<z.ZodBoolean>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
 } & {
     type: z.ZodLiteral<"image">;
     aspect: z.ZodOptional<z.ZodString>;
@@ -46,6 +47,7 @@ export declare const imageFieldSchema: z.ZodObject<{
     list?: boolean | undefined;
     isTitle?: boolean | undefined;
     isBody?: boolean | undefined;
+    maxItems?: number | undefined;
     aspect?: string | undefined;
     altOptional?: boolean | undefined;
 }, {
@@ -57,9 +59,16 @@ export declare const imageFieldSchema: z.ZodObject<{
     list?: boolean | undefined;
     isTitle?: boolean | undefined;
     isBody?: boolean | undefined;
+    maxItems?: number | undefined;
     aspect?: string | undefined;
     altOptional?: boolean | undefined;
 }>;
+/**
+ * A dotted field path for `optionSort: { field }`: non-empty segments, so `'a..b'` and `'.a'`
+ * fail at config time rather than sorting on a value no entry has.
+ * @internal Exported for the reference-options endpoint, which validates `sortField` the same way.
+ */
+export declare const referenceSortFieldSchema: z.ZodString;
 /** @internal Exported for tests. */
 export declare const referenceFieldSchema: z.ZodObject<{
     name: z.ZodString;
@@ -69,6 +78,7 @@ export declare const referenceFieldSchema: z.ZodObject<{
     list: z.ZodOptional<z.ZodBoolean>;
     isTitle: z.ZodOptional<z.ZodBoolean>;
     isBody: z.ZodOptional<z.ZodBoolean>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
 } & {
     type: z.ZodLiteral<"reference">;
     collections: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -85,6 +95,16 @@ export declare const referenceFieldSchema: z.ZodObject<{
         label: string;
     }>]>, "many">>;
     includeBody: z.ZodOptional<z.ZodBoolean>;
+    optionSort: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["label", "collection"]>, z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
+    }, "strict", z.ZodTypeAny, {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+    }, {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+    }>]>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     type: "reference";
@@ -98,10 +118,15 @@ export declare const referenceFieldSchema: z.ZodObject<{
     list?: boolean | undefined;
     isTitle?: boolean | undefined;
     isBody?: boolean | undefined;
+    maxItems?: number | undefined;
     collections?: string[] | undefined;
     entryTypes?: string[] | undefined;
     displayField?: string | undefined;
     includeBody?: boolean | undefined;
+    optionSort?: "collection" | "label" | {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+    } | undefined;
 }, {
     name: string;
     type: "reference";
@@ -115,10 +140,15 @@ export declare const referenceFieldSchema: z.ZodObject<{
     list?: boolean | undefined;
     isTitle?: boolean | undefined;
     isBody?: boolean | undefined;
+    maxItems?: number | undefined;
     collections?: string[] | undefined;
     entryTypes?: string[] | undefined;
     displayField?: string | undefined;
     includeBody?: boolean | undefined;
+    optionSort?: "collection" | "label" | {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+    } | undefined;
 }>;
 export declare const blockSchema: z.ZodObject<{
     name: z.ZodString;

package/dist/config/schemas/field.js

@@ -12,6 +12,9 @@ const fieldBaseSchema = z.object({
     list: z.boolean().optional(),
     isTitle: z.boolean().optional(),
     isBody: z.boolean().optional(),
+    // Listed so a parse keeps it (zod strips unknown keys); which fields may carry it is
+    // `ensureMaxItemsPlacement`'s call (config/validation.ts).
+    maxItems: z.number().int().positive().optional(),
 });
 export const selectOptionSchema = z.union([
     z.string(),
@@ -94,6 +97,14 @@ const selectFieldSchema = fieldBaseSchema.extend({
     type: z.literal('select'),
     options: z.array(selectOptionSchema).min(1),
 });
+/**
+ * A dotted field path for `optionSort: { field }`: non-empty segments, so `'a..b'` and `'.a'`
+ * fail at config time rather than sorting on a value no entry has.
+ * @internal Exported for the reference-options endpoint, which validates `sortField` the same way.
+ */
+export const referenceSortFieldSchema = z
+    .string()
+    .regex(/^[^.]+(\.[^.]+)*$/, 'must be a field name or a dotted path such as "meta.publishedAt"');
 // At least one of `collections` or `entryTypes` must be specified (enforced by config validation).
 /** @internal Exported for tests. */
 export const referenceFieldSchema = fieldBaseSchema.extend({
@@ -107,6 +118,17 @@ export const referenceFieldSchema = fieldBaseSchema.extend({
     // runtime-consumed flag and the feature would no-op with no error. (`resolvedSchema` is
     // absent on purpose — it is type-inference-only and stripping it changes no behavior.)
     includeBody: z.boolean().optional(),
+    optionSort: z
+        .union([
+        z.enum(['label', 'collection']),
+        z
+            .object({
+            field: referenceSortFieldSchema,
+            direction: z.enum(['asc', 'desc']).optional(),
+        })
+            .strict(),
+    ])
+        .optional(),
 });
 // Use a mutable holder to enable forward references in recursive z.lazy() closures.
 // blockSchema/objectFieldSchema reference fieldHolder[0] via z.lazy, which is resolved

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 {};