canopycms 0.3.3 → 0.5.0

package/dist/editor/fields/StringListField.js

@@ -1,27 +1,37 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from 'react';
 import { TagsInput } from '@mantine/core';
+import { listFullReason } from '../copy.js';
 import { LabelledInput } from './FieldLabel.js';
-/** The field's description, ended as a sentence, then the hint that Enter adds. */
-const withEnterHint = (description) => {
+/**
+ * `maxTags` for a TagsInput holding `count` items: never below `count`, since a paste cuts the list
+ * to `maxTags` and would drop stored items without a word.
+ */
+export const tagCap = (count, maxItems) => maxItems === undefined ? undefined : Math.max(count, maxItems);
+/** The field's description, ended as a sentence, then `hint`. */
+export const withHint = (description, hint) => {
     const own = description?.trim();
     if (!own)
-        return 'Press Enter to add.';
-    return `${/[.!?]$/.test(own) ? own : `${own}.`} Press Enter to add.`;
+        return hint;
+    return `${/[.!?]$/.test(own) ? own : `${own}.`} ${hint}`;
 };
 /**
  * Editor for `type: 'string', list: true` fields.
  *
  * Uses Mantine's TagsInput: type + Enter adds an item, each item renders as a
  * removable pill, and Backspace on an empty input removes the last item. An editable list says
- * that Enter adds, after the field's own description.
+ * that Enter adds, after the field's own description, or at `maxItems` why it adds no more.
  */
-export const StringListField = ({ id, label, description, value, onChange, dataCanopyField, readOnly = false, }) => {
+export const StringListField = ({ id, label, description, value, onChange, dataCanopyField, readOnly = false, maxItems, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     return (_jsx(LabelledInput, { label: label, inputId: inputId, canopyPath: dataCanopyField, children: _jsx(TagsInput, { id: inputId, 
-            // TagsInput gives no sign that Enter adds a typed item.
-            description: readOnly ? description : withEnterHint(description), value: value, size: "sm", readOnly: readOnly, onChange: (next) => {
+            // TagsInput gives no sign that Enter adds a typed item, nor why it stops at `maxTags`.
+            description: readOnly
+                ? description
+                : withHint(description, maxItems !== undefined && value.length >= maxItems
+                    ? listFullReason(maxItems)
+                    : 'Press Enter to add.'), maxTags: tagCap(value.length, maxItems), value: value, size: "sm", readOnly: readOnly, onChange: (next) => {
                 if (!readOnly)
                     onChange(next);
             }, 

package/dist/editor/fields/item-expansion.d.ts

@@ -9,7 +9,11 @@ export interface ItemExpansion {
  * Which rows of a collapsible list are open, by list-item key (`useListItemKeys`), so a row keeps
  * its state through moves, and through a Remove and its Undo. A list inside a row that moves
  * remounts and starts over. A list's first rows start open as `EXPAND_ALL_UP_TO` says; a row added
- * later (Add, Duplicate) starts open. `resetKey` names the entry being edited: a new one starts
- * over. The form's own Expand all and Collapse all (`FormExpansionContext`) reach every list.
+ * later (Add, Duplicate) starts open. With `rowsStartOpen: false`, every row starts shut, for a
+ * list whose collapsed rows already say all it holds. `resetKey` names the entry being edited: a
+ * new one starts over. The form's own Expand all and Collapse all (`FormExpansionContext`) reach
+ * every list.
  */
-export declare function useItemExpansion(itemKeys: readonly string[], resetKey: string): ItemExpansion;
+export declare function useItemExpansion(itemKeys: readonly string[], resetKey: string, { rowsStartOpen }?: {
+    rowsStartOpen?: boolean;
+}): ItemExpansion;

package/dist/editor/fields/item-expansion.js

@@ -6,10 +6,12 @@ const EXPAND_ALL_UP_TO = 3;
  * Which rows of a collapsible list are open, by list-item key (`useListItemKeys`), so a row keeps
  * its state through moves, and through a Remove and its Undo. A list inside a row that moves
  * remounts and starts over. A list's first rows start open as `EXPAND_ALL_UP_TO` says; a row added
- * later (Add, Duplicate) starts open. `resetKey` names the entry being edited: a new one starts
- * over. The form's own Expand all and Collapse all (`FormExpansionContext`) reach every list.
+ * later (Add, Duplicate) starts open. With `rowsStartOpen: false`, every row starts shut, for a
+ * list whose collapsed rows already say all it holds. `resetKey` names the entry being edited: a
+ * new one starts over. The form's own Expand all and Collapse all (`FormExpansionContext`) reach
+ * every list.
  */
-export function useItemExpansion(itemKeys, resetKey) {
+export function useItemExpansion(itemKeys, resetKey, { rowsStartOpen = true } = {}) {
     const [toggled, setToggled] = useState(() => ({
         resetKey,
         open: new Map(),
@@ -27,7 +29,7 @@ export function useItemExpansion(itemKeys, resetKey) {
     itemKeys.forEach((key, idx) => {
         if (defaults.current.open.has(key))
             return;
-        defaults.current.open.set(key, firstPopulation ? idx === 0 || itemKeys.length <= EXPAND_ALL_UP_TO : true);
+        defaults.current.open.set(key, rowsStartOpen && (firstPopulation ? idx === 0 || itemKeys.length <= EXPAND_ALL_UP_TO : true));
     });
     if (itemKeys.length > 0)
         defaults.current.started = true;

package/dist/editor/fields/list-item-keys.d.ts

@@ -1,8 +1,9 @@
 /**
- * Keys for the items of object lists and block lists. An object listed once keeps the key it
- * was first shown with, so an append remounts no item, a removal never hands a crashed item's
- * boundary to the next one, and an item put back by Undo (the same object) gets its key back. A
- * list whose length is unchanged (an edited item, the saved copy of the same items) keeps keys by
- * position. One instance serves every list a component renders, told apart by `listPath`.
+ * Keys for the items of object lists, block lists and reference lists. An object, or a string,
+ * listed once keeps the key it was first shown with, so a move carries its row's state along, an
+ * append remounts no item, a removal never hands a crashed item's boundary to the next one, and an
+ * item put back by Undo (the same object, the same string) gets its key back. A list whose length
+ * is unchanged (an edited item, a repointed reference, the saved copy of the same items) keeps keys
+ * by position. One instance serves every list a component renders, told apart by `listPath`.
  */
 export declare function useListItemKeys(): (items: readonly unknown[], listPath: string) => string[];

package/dist/editor/fields/list-item-keys.js

@@ -1,50 +1,82 @@
 import { useRef } from 'react';
 /**
- * Keys for the items of object lists and block lists. An object listed once keeps the key it
- * was first shown with, so an append remounts no item, a removal never hands a crashed item's
- * boundary to the next one, and an item put back by Undo (the same object) gets its key back. A
- * list whose length is unchanged (an edited item, the saved copy of the same items) keeps keys by
- * position. One instance serves every list a component renders, told apart by `listPath`.
+ * Keys for the items of object lists, block lists and reference lists. An object, or a string,
+ * listed once keeps the key it was first shown with, so a move carries its row's state along, an
+ * append remounts no item, a removal never hands a crashed item's boundary to the next one, and an
+ * item put back by Undo (the same object, the same string) gets its key back. A list whose length
+ * is unchanged (an edited item, a repointed reference, the saved copy of the same items) keeps keys
+ * by position. One instance serves every list a component renders, told apart by `listPath`.
  */
 export function useListItemKeys() {
     const listItemKeys = useRef(new WeakMap());
+    // Strings can't key a WeakMap, and one id may sit in two lists, so each list keeps its own.
+    const stringKeys = useRef(new Map());
     const lastListKeys = useRef(new Map());
+    const lastListItems = useRef(new Map());
     const nextListItemKey = useRef(0);
     return (items, listPath) => {
         const previous = lastListKeys.current.get(listPath);
+        const previousItems = lastListItems.current.get(listPath);
+        let ownStrings = stringKeys.current.get(listPath);
+        if (!ownStrings) {
+            ownStrings = new Map();
+            stringKeys.current.set(listPath, ownStrings);
+        }
         const occurrences = new Map();
         for (const item of items) {
-            if (typeof item === 'object' && item !== null) {
+            if ((typeof item === 'object' && item !== null) || typeof item === 'string') {
                 occurrences.set(item, (occurrences.get(item) ?? 0) + 1);
             }
         }
-        // Only an object listed once has an identity; a repeated one is keyed by position.
-        const single = (item) => typeof item === 'object' && item !== null && occurrences.get(item) === 1;
+        // Only an item listed once has an identity; a repeated one is keyed by position.
+        const single = (item) => ((typeof item === 'object' && item !== null) || typeof item === 'string') &&
+            occurrences.get(item) === 1;
+        const sameLength = previous?.length === items.length;
+        const ownKey = (item) => {
+            if (typeof item !== 'string')
+                return listItemKeys.current.get(item);
+            // A string new to a list of unchanged length took an item's place (a repoint), so it takes
+            // that position's key rather than one it held before.
+            if (sameLength && !previousItems?.includes(item))
+                return undefined;
+            return ownStrings.get(item);
+        };
         const claimed = new Set();
         const keys = items.map((item) => {
-            const own = single(item) ? listItemKeys.current.get(item) : undefined;
+            const own = single(item) ? ownKey(item) : undefined;
             // Two objects can hold one key, an edited copy having inherited its original's.
             if (own === undefined || claimed.has(own))
                 return undefined;
             claimed.add(own);
             return own;
         });
-        // The rest inherit their position's key, never one an object present here holds.
+        // The rest inherit their position's key, never one an item present here holds.
         const resolved = keys.map((key, idx) => {
             if (key !== undefined)
                 return key;
-            let next = previous?.length === items.length ? previous[idx] : undefined;
+            let next = sameLength ? previous?.[idx] : undefined;
             if (next === undefined || claimed.has(next)) {
                 nextListItemKey.current += 1;
                 next = `item-${nextListItemKey.current}`;
             }
             claimed.add(next);
             const item = items[idx];
-            if (single(item))
-                listItemKeys.current.set(item, next);
+            if (single(item)) {
+                if (typeof item === 'string') {
+                    // The string it replaced gives the key up, so that string returns with a key of its own.
+                    for (const [held, key] of ownStrings)
+                        if (key === next)
+                            ownStrings.delete(held);
+                    ownStrings.set(item, next);
+                }
+                else {
+                    listItemKeys.current.set(item, next);
+                }
+            }
             return next;
         });
         lastListKeys.current.set(listPath, resolved);
+        lastListItems.current.set(listPath, items);
         return resolved;
     };
 }

package/dist/editor/fields/reference-noindex.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import { type ComboboxItem } from '@mantine/core';
+import type { ReferenceOption } from './use-reference-options.js';
+/** The badge on a picked or offered entry whose own form hides it from search. */
+export declare const HIDDEN_FROM_SEARCH = "Hidden from search";
+/** `inOption` lets a highlighted option's fill recolour it (theme.tsx), so it stays legible. */
+export declare const HiddenFromSearchBadge: React.FC<{
+    inOption?: boolean;
+}>;
+/**
+ * A reference Select's `renderOption`: the label, with the badge on a hidden entry. Draws the
+ * check mark itself, since a custom option replaces Mantine's.
+ */
+export declare function referenceOptionRenderer(options: readonly ReferenceOption[]): ({ option, checked, }: {
+    option: ComboboxItem;
+    checked?: boolean;
+}) => import("react/jsx-runtime").JSX.Element;
+/** A pick whose target is hidden from search, as the note names it. */
+export interface HiddenPick {
+    label: string;
+    fieldLabel: string;
+}
+/**
+ * One sentence per noindex field label, since entry types can label that field differently:
+ * "‘A’ has “Hide from search engines” turned on, so pages that list only visible entries won't
+ * show it."
+ * @internal Exported for tests.
+ */
+export declare function hiddenPickSentences(picks: readonly HiddenPick[]): string[];
+/**
+ * The yellow note about hidden picks: above a list, under its heading, or under a single
+ * field's input. It warns rather than filters: an editor may be lining up an entry that is
+ * about to go public.
+ */
+export declare const HiddenPicksNote: React.FC<{
+    picks: readonly HiddenPick[];
+}>;

package/dist/editor/fields/reference-noindex.js

@@ -0,0 +1,48 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, Badge, Group } from '@mantine/core';
+import { IconAlertTriangle, IconCheck } from '@tabler/icons-react';
+/** The badge on a picked or offered entry whose own form hides it from search. */
+export const HIDDEN_FROM_SEARCH = 'Hidden from search';
+/** `inOption` lets a highlighted option's fill recolour it (theme.tsx), so it stays legible. */
+export const HiddenFromSearchBadge = ({ inOption }) => (_jsx(Badge, { variant: "light", color: "yellow", size: "sm", tt: "none", style: { flexShrink: 0 }, ...(inOption && { 'data-canopy-option-badge': true }), children: HIDDEN_FROM_SEARCH }));
+/**
+ * A reference Select's `renderOption`: the label, with the badge on a hidden entry. Draws the
+ * check mark itself, since a custom option replaces Mantine's.
+ */
+export function referenceOptionRenderer(options) {
+    const hiddenValues = new Set(options.flatMap((o) => (o.noindex ? [o.value] : [])));
+    return function ReferenceOptionLabel({ option, checked, }) {
+        const hidden = hiddenValues.has(option.value);
+        return (_jsxs(Group, { gap: 6, wrap: "nowrap", w: "100%", children: [_jsx(IconCheck, { "aria-hidden": true, size: 14, style: { visibility: checked ? 'visible' : 'hidden' } }), _jsx("span", { style: { flex: 1, minWidth: 0 }, children: option.label }), hidden && _jsx(HiddenFromSearchBadge, { inOption: true })] }));
+    };
+}
+const quoted = (label) => `‘${label}’`;
+const listNames = (names) => names.length === 1 ? names[0] : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+/**
+ * One sentence per noindex field label, since entry types can label that field differently:
+ * "‘A’ has “Hide from search engines” turned on, so pages that list only visible entries won't
+ * show it."
+ * @internal Exported for tests.
+ */
+export function hiddenPickSentences(picks) {
+    const byField = new Map();
+    for (const pick of picks) {
+        byField.set(pick.fieldLabel, [...(byField.get(pick.fieldLabel) ?? []), quoted(pick.label)]);
+    }
+    return [...byField].map(([fieldLabel, names]) => {
+        const one = names.length === 1;
+        return (`${listNames(names)} ${one ? 'has' : 'have'} “${fieldLabel}” turned on, so pages ` +
+            `that list only visible entries won't show ${one ? 'it' : 'them'}.`);
+    });
+}
+/**
+ * The yellow note about hidden picks: above a list, under its heading, or under a single
+ * field's input. It warns rather than filters: an editor may be lining up an entry that is
+ * about to go public.
+ */
+export const HiddenPicksNote = ({ picks }) => {
+    if (picks.length === 0)
+        return null;
+    return (_jsx(Alert, { color: "yellow", icon: _jsx(IconAlertTriangle, { size: 16 }), p: "xs", "data-testid": "reference-hidden-note", children: hiddenPickSentences(picks).map((sentence) => (_jsx("div", { children: sentence }, sentence))) }));
+};

package/dist/editor/fields/use-reference-options.d.ts

@@ -0,0 +1,36 @@
+import type { ReferenceOptionSort } from '../../config/index.js';
+/** An entry a reference field can point at. */
+export interface ReferenceOption {
+    value: string;
+    label: string;
+    /** The target is hidden from search; `fieldLabel` names the setting on that entry's form. */
+    noindex?: {
+        fieldLabel: string;
+    };
+}
+/** The id a stored reference holds: the id itself, or a resolved read's `{ id, … }`. */
+export declare const extractId: (val: unknown) => string;
+/** Label for a set value the options omit (a restricted, missing or unlisted target). */
+export declare function unlistedReferenceLabel(value: unknown, id: string): string;
+export interface ReferenceOptionsQuery {
+    /** Used as given, with no fetch. */
+    staticOptions?: ReferenceOption[];
+    collections?: string[];
+    entryTypes?: string[];
+    displayField: string;
+    branch: string;
+    /** The order the endpoint returns options in. Default: by label. */
+    optionSort?: ReferenceOptionSort;
+}
+export interface ReferenceOptions {
+    options: ReferenceOption[];
+    loading: boolean;
+    error: string | null;
+    retry: () => void;
+}
+/**
+ * The entries a reference field offers: `staticOptions` as given, else one request per field to
+ * the reference-options endpoint, made again only when the query or the API client changes, or on
+ * `retry`.
+ */
+export declare function useReferenceOptions({ staticOptions, collections, entryTypes, displayField, branch, optionSort, }: ReferenceOptionsQuery): ReferenceOptions;

package/dist/editor/fields/use-reference-options.js

@@ -0,0 +1,121 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { createApiClient } from '../../api/client.js';
+import { getErrorMessage } from '../../utils/error.js';
+import { useOptionalApiClient } from '../context/index.js';
+/** The id a stored reference holds: the id itself, or a resolved read's `{ id, … }`. */
+export const extractId = (val) => {
+    if (typeof val === 'string')
+        return val;
+    if (val && typeof val === 'object' && 'id' in val && typeof val.id === 'string')
+        return val.id;
+    return '';
+};
+/** Label for a set value the options omit (a restricted, missing or unlisted target). */
+export function unlistedReferenceLabel(value, id) {
+    if (value && typeof value === 'object' && 'unavailable' in value && value.unavailable === true) {
+        if ('reason' in value && value.reason === 'restricted' && 'title' in value) {
+            return `Restricted entry: ${String(value.title)}`;
+        }
+        return `Missing entry (${id})`;
+    }
+    return `Unavailable entry (${id})`;
+}
+/** `optionSort` as the reference-options endpoint's `sort`, `sortField` and `sortDir` params. */
+function sortParams(sort) {
+    if (sort === undefined)
+        return {};
+    if (typeof sort === 'string')
+        return { sort };
+    return {
+        sort: 'field',
+        sortField: sort.field,
+        ...(sort.direction && { sortDir: sort.direction }),
+    };
+}
+/**
+ * The entries a reference field offers: `staticOptions` as given, else one request per field to
+ * the reference-options endpoint, made again only when the query or the API client changes, or on
+ * `retry`.
+ */
+export function useReferenceOptions({ staticOptions, collections, entryTypes, displayField, branch, optionSort, }) {
+    // `null` outside an ApiClientProvider (some stories), so the fetch falls back to a
+    // default-configured client.
+    const contextApiClient = useOptionalApiClient();
+    const hasCollections = !!collections && collections.length > 0;
+    const hasEntryTypes = !!entryTypes && entryTypes.length > 0;
+    const needsFetch = !staticOptions && (hasCollections || hasEntryTypes);
+    const [fetched, setFetched] = useState([]);
+    const [loading, setLoading] = useState(needsFetch);
+    const [error, setError] = useState(null);
+    const [retryCount, setRetryCount] = useState(0);
+    // A changed query starts loading in the same render, so no stale option list shows meanwhile.
+    const [prevFetchKey, setPrevFetchKey] = useState('');
+    const fetchKey = needsFetch
+        ? `${collections?.join(',') ?? ''}:${entryTypes?.join(',') ?? ''}:${displayField}:${branch}:${JSON.stringify(optionSort ?? null)}`
+        : '';
+    if (fetchKey !== prevFetchKey) {
+        setPrevFetchKey(fetchKey);
+        if (needsFetch) {
+            setLoading(true);
+            setError(null);
+        }
+    }
+    // Keyed on `fetchKey`, not the `collections`/`entryTypes` arrays, which the parent rebuilds on
+    // every render, so those and `displayField`/`branch`/`optionSort` are left out of the deps on
+    // purpose.
+    // `active` drops a response a newer request or an unmount has superseded.
+    useEffect(() => {
+        if (!needsFetch)
+            return;
+        let active = true;
+        const apiClient = contextApiClient ?? createApiClient();
+        const params = { branch, displayField };
+        if (collections && collections.length > 0)
+            params.collections = collections.join(',');
+        if (entryTypes && entryTypes.length > 0)
+            params.entryTypes = entryTypes.join(',');
+        Object.assign(params, sortParams(optionSort));
+        apiClient.content
+            .getReferenceOptions(params)
+            .then((response) => {
+            if (!active)
+                return;
+            if (response.ok && response.data?.options) {
+                setFetched(response.data.options.map((opt) => ({
+                    value: opt.id,
+                    label: opt.label,
+                    ...(opt.noindex ? { noindex: opt.noindex } : {}),
+                })));
+            }
+            else {
+                setError(response.error || 'Failed to load reference options');
+            }
+        })
+            .catch((err) => {
+            if (!active)
+                return;
+            console.error('Failed to load reference options:', err);
+            setError(getErrorMessage(err));
+        })
+            .finally(() => {
+            if (!active)
+                return;
+            setLoading(false);
+        });
+        return () => {
+            active = false;
+        };
+    }, [needsFetch, fetchKey, retryCount, contextApiClient]);
+    const retry = () => {
+        setLoading(true);
+        setError(null);
+        setRetryCount((count) => count + 1);
+    };
+    return {
+        options: staticOptions ?? fetched,
+        loading: needsFetch && loading,
+        error: needsFetch ? error : null,
+        retry,
+    };
+}

package/dist/editor/form-outline.d.ts

@@ -7,7 +7,7 @@ import type { OutlineNode } from './FormHeader.js';
  */
 export declare function buildFormOutline(fields: readonly FieldConfig[], value: Record<string, unknown>, customTypes?: ReadonlySet<string>): OutlineNode[];
 /**
- * True when some field, at any depth, is a block field or a list of objects that the form draws
- * itself: a type in `customTypes` has a custom renderer.
+ * True when some field, at any depth, is a block field or a list of objects or references that the
+ * form draws itself: a type in `customTypes` has a custom renderer.
  */
 export declare function hasCollapsibleList(fields: readonly FieldConfig[], customTypes?: ReadonlySet<string>): boolean;

package/dist/editor/form-outline.js

@@ -49,8 +49,8 @@ export function buildFormOutline(fields, value, customTypes = new Set()) {
     return fields.map(nodeOf);
 }
 /**
- * True when some field, at any depth, is a block field or a list of objects that the form draws
- * itself: a type in `customTypes` has a custom renderer.
+ * True when some field, at any depth, is a block field or a list of objects or references that the
+ * form draws itself: a type in `customTypes` has a custom renderer.
  */
 export function hasCollapsibleList(fields, customTypes = new Set()) {
     return fields.some((field) => {
@@ -58,6 +58,8 @@ export function hasCollapsibleList(fields, customTypes = new Set()) {
             return false;
         if (field.type === 'block')
             return true;
+        if (field.type === 'reference' && field.list === true)
+            return true;
         if (field.type === 'group') {
             return hasCollapsibleList(field.fields, customTypes);
         }

package/dist/editor/theme.js

@@ -377,6 +377,11 @@ const CANOPY_STYLES = `
 [data-combobox-selected] {
   --mantine-primary-color-filled: var(--canopy-primary-fill);
 }
+[data-combobox-selected] [data-canopy-option-badge] {
+  color: inherit;
+  background: transparent;
+  box-shadow: inset 0 0 0 1px currentColor;
+}
 .mantine-DateTimePicker-day[data-selected],
 .mantine-DateTimePicker-pickerControl[data-selected] {
   background-color: var(--canopy-primary-fill);

package/dist/entry-schema-registry.d.ts

@@ -18,7 +18,7 @@ import type { EntrySchemaRegistry } from './schema/types.js';
  * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: field names a path can spell, select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups inside object/block fields,
- * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement.
+ * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement, `maxItems` placement.
  *
  * @example
  * ```typescript

package/dist/entry-schema-registry.js

@@ -2,7 +2,7 @@ import { countTitleFields, findInvalidTitleFields, findTitleFieldsInLists, } fro
 import { countBodyFields, findInvalidBodyFields, findReservedBodyFieldName, } from './utils/body-field.js';
 import { RESOLVED_REFERENCE_KEYS, RESTRICTED_REFERENCE_MARKER } from './entry-schema.js';
 import { flattenGroupFields } from './utils/flatten-group-fields.js';
-import { ensureFieldNamesSpellInPaths, ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureItemTitleFieldsExist, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, ensureMarkdownFieldOptions, ensureStampOnPublishPlacement, } from './config/validation.js';
+import { ensureFieldNamesSpellInPaths, ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureItemTitleFieldsExist, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, ensureMarkdownFieldOptions, ensureMaxItemsPlacement, ensureStampOnPublishPlacement, } from './config/validation.js';
 /** Look up a field's type by dotted path (e.g., "meta.order").
  * Groups are transparent — their children are searched at the same path level. */
 function findFieldType(fields, dottedPath) {
@@ -41,7 +41,7 @@ function findFieldType(fields, dottedPath) {
  * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: field names a path can spell, select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups inside object/block fields,
- * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement.
+ * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement, `maxItems` placement.
  *
  * @example
  * ```typescript
@@ -102,6 +102,7 @@ export function createEntrySchemaRegistry(registry) {
         ensureNoGroupsInsideComplexFields(schema);
         ensureMarkdownFieldOptions(schema);
         ensureStampOnPublishPlacement(schema, `Entry schema registry entry "${key}"`);
+        ensureMaxItemsPlacement(schema, `Entry schema registry entry "${key}"`);
         ensureNoFlattenedFieldNameCollisions(schema, `entry schema "${key}"`);
     }
     return registry;

package/dist/entry-schema.d.ts

@@ -48,7 +48,10 @@ type InferableField = {
     entryTypes?: readonly string[];
     /** For reference fields: collection paths to scope the search. */
     collections?: readonly string[];
-    /** For reference fields: resolve the target's body too. See ReferenceFieldConfig.includeBody. */
+    /**
+     * For reference fields: resolve the target's body too. Without it the `resolvedSchema`'s
+     * `isBody` field is optional in the resolved type. See ReferenceFieldConfig.includeBody.
+     */
     includeBody?: boolean;
 };
 /**
@@ -79,7 +82,9 @@ export interface ResolvedReferenceMeta {
 }
 /**
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
- * embed it, then the reserved metadata.
+ * embed it, then the reserved metadata. A link-only reference carries no body for any format:
+ * an md/mdx target passes none here, and a json/yaml target's `data` arrives without its
+ * `isBody` field (`linkOnlyReferenceData`), so both formats resolve alike.
  *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from
@@ -272,7 +277,7 @@ type FieldValue<F extends InferableField> = F extends {
 } ? ScalarValue<F, SelectValue<F>> : F extends {
     type: 'reference';
     resolvedSchema: infer S;
-} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>> & ResolvedReferenceMeta & {
+} ? ScalarValue<F, (InferContentShape<Extract<S, readonly InferableField[]>, F['includeBody'] extends true ? false : true> & ResolvedReferenceMeta & {
     unavailable?: undefined;
 }) | UnavailableReference | null> : F extends {
     type: 'reference';
@@ -298,11 +303,16 @@ type FieldValue<F extends InferableField> = F extends {
  *
  * Works with any structurally compatible array; importing FieldConfig is not required.
  */
-type InferContentShape<Fields extends readonly InferableField[]> = Simplify<{
-    [F in FlattenInlineGroups<Fields>[number] as F['required'] extends false ? never : F['name']]: FieldValue<F>;
+type InferContentShape<Fields extends readonly InferableField[], BodyOptional extends boolean = false> = Simplify<{
+    [F in FlattenInlineGroups<Fields>[number] as IsOptionalKey<F, BodyOptional> extends true ? never : F['name']]: FieldValue<F>;
 } & {
-    [F in FlattenInlineGroups<Fields>[number] as F['required'] extends false ? F['name'] : never]?: FieldValue<F>;
+    [F in FlattenInlineGroups<Fields>[number] as IsOptionalKey<F, BodyOptional> extends true ? F['name'] : never]?: FieldValue<F>;
 }>;
+/**
+ * Whether InferContentShape gives a field `?:`: an explicit `required: false`, or, with
+ * `BodyOptional` (a reference target resolved without `includeBody`), the `isBody` field.
+ */
+type IsOptionalKey<F extends InferableField, BodyOptional extends boolean> = F['required'] extends false ? true : BodyOptional extends true ? F['isBody'] extends true ? true : false : false;
 /** Define an entry schema's field array with literal inference, without sprinkling `as const`. */
 export declare const defineEntrySchema: <const T extends readonly InferableField[]>(fields: T) => T;
 /** Content shape derived from a `defineEntrySchema` result. */
@@ -362,7 +372,8 @@ export declare const defineInlineFieldGroup: <const T extends {
  *
  * **Flat by default** — an inline group, stored at the top level of the content file with no data
  * key of its own. `group: 'seo'` nests them under that key instead, and the same
- * `{ group: 'seo' }` must then be passed to `extractSeoFields` / `entryToMetadata`.
+ * `{ group: 'seo' }` must then be set as `seo` in `defineCanopyConfig`, or passed to
+ * `extractSeoFields` and the free `entryToMetadata`.
  *
  * @example
  * // Flat (recommended): frontmatter carries `metaTitle:` at the top level.
@@ -451,8 +462,9 @@ export declare function defineSeoFieldGroup(opts?: SeoFieldGroupOptions & {
 }): InlineSeoFieldGroup;
 export declare function defineSeoFieldGroup<const G extends string>(opts: SeoFieldGroupOptions & {
     /**
-     * Nest the fields under this data key instead of storing them flat. Must match the `group`
-     * option passed to `extractSeoFields` / `entryToMetadata`.
+     * Nest the fields under this data key instead of storing them flat. Must match
+     * `CanopyConfig.seo.group`, or the `group` passed to `extractSeoFields` and the free
+     * `entryToMetadata`.
      */
     group: G;
 }): NestedSeoFieldGroup<G>;

package/dist/entry-schema.js

@@ -12,7 +12,9 @@ import { DEFAULT_SEO_FIELD_NAMES } from './static/seo.js';
 export const RESOLVED_REFERENCE_KEYS = ['id', 'slug', 'collection', 'urlPath'];
 /**
  * Assemble a resolved reference: the target's own data, then its body if the field asked to
- * embed it, then the reserved metadata.
+ * embed it, then the reserved metadata. A link-only reference carries no body for any format:
+ * an md/mdx target passes none here, and a json/yaml target's `data` arrives without its
+ * `isBody` field (`linkOnlyReferenceData`), so both formats resolve alike.
  *
  * The ordering is the contract, not a detail. Metadata LAST means a target that models `id` as
  * a content field cannot shadow the real content ID, which the write boundary recovers from
@@ -99,7 +101,8 @@ export const defineInlineFieldGroup = (group) => ({ ...group, type: 'group' });
  *
  * **Flat by default** — an inline group, stored at the top level of the content file with no data
  * key of its own. `group: 'seo'` nests them under that key instead, and the same
- * `{ group: 'seo' }` must then be passed to `extractSeoFields` / `entryToMetadata`.
+ * `{ group: 'seo' }` must then be set as `seo` in `defineCanopyConfig`, or passed to
+ * `extractSeoFields` and the free `entryToMetadata`.
  *
  * @example
  * // Flat (recommended): frontmatter carries `metaTitle:` at the top level.