canopycms 0.3.3 → 0.5.0

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;

package/dist/editor/fields/ReferenceField.js

@@ -1,136 +1,42 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useId, useState } from 'react';
-import { Alert, Button, MultiSelect, Select, Stack, Text, Loader } from '@mantine/core';
+import { useId, useMemo } from 'react';
+import { Alert, Button, Group, Select, Stack, Text, Loader } from '@mantine/core';
 import { IconAlertCircle } from '@tabler/icons-react';
-import { createApiClient } from '../../api/client.js';
-import { useOptionalApiClient } from '../context/index.js';
-import { getErrorMessage } from '../../utils/error.js';
 import { useFieldCommentControl } from '../comments/field-comment-context.js';
 import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 import { FieldLabel } from './FieldLabel.js';
-/** Label for a set value the options omit (a restricted, missing or unlisted target). */
-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})`;
-}
-export const ReferenceField = ({ id, label, description, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', value, onChange, multiple, dataCanopyField, readOnly = false, }) => {
-    // Configured with the deployment's basePath when rendered inside an
-    // ApiClientProvider (always true in the real Editor tree); `null` outside one
-    // (e.g. FormRenderer.stories.tsx), so the fetch effect 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 [options, setOptions] = useState(staticOptions || []);
-    const [loading, setLoading] = useState(needsFetch);
-    const [error, setError] = useState(null);
-    const [retryCount, setRetryCount] = useState(0);
-    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 '';
-    };
-    const normalizedValue = multiple
-        ? Array.isArray(value)
-            ? value.map(extractId)
-            : []
-        : extractId(value);
+import { HiddenFromSearchBadge, HiddenPicksNote, referenceOptionRenderer, } from './reference-noindex.js';
+import { extractId, unlistedReferenceLabel, useReferenceOptions, } from './use-reference-options.js';
+export const ReferenceField = ({ id, label, description, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', optionSort, value, onChange, dataCanopyField, readOnly = false, }) => {
+    const { options, loading, error, retry } = useReferenceOptions({
+        staticOptions,
+        collections,
+        entryTypes,
+        displayField,
+        branch,
+        optionSort,
+    });
+    const normalizedValue = extractId(value);
     // Otherwise Select shows a set value as empty, inviting an editor to repoint it.
     const listed = new Set(options.map((option) => option.value));
-    const unlisted = new Map();
-    for (const raw of multiple ? (Array.isArray(value) ? value : []) : [value]) {
-        const valueId = extractId(raw);
-        if (valueId && !listed.has(valueId) && !unlisted.has(valueId)) {
-            unlisted.set(valueId, { value: valueId, label: unlistedReferenceLabel(raw, valueId) });
-        }
-    }
-    const data = unlisted.size > 0 ? [...options, ...unlisted.values()] : options;
+    const data = normalizedValue && !listed.has(normalizedValue)
+        ? [
+            ...options,
+            { value: normalizedValue, label: unlistedReferenceLabel(value, normalizedValue) },
+        ]
+        : options;
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const commentControl = useFieldCommentControl(dataCanopyField);
-    // Track deps to detect changes and reset loading during render
-    const [prevFetchKey, setPrevFetchKey] = useState('');
-    const fetchKey = needsFetch
-        ? `${collections?.join(',') ?? ''}:${entryTypes?.join(',') ?? ''}:${displayField}:${branch}`
-        : '';
-    if (fetchKey !== prevFetchKey) {
-        setPrevFetchKey(fetchKey);
-        if (needsFetch) {
-            setLoading(true);
-            setError(null);
-        }
-    }
-    // Keyed on the derived `fetchKey`, not the raw `collections`/`entryTypes`
-    // arrays: the parent rebuilds those on every render (including every
-    // `refreshEntries()` after a save), so depending on them directly fired
-    // this fetch far more often than the inputs actually changed.
-    //
-    // `active` guards against a stale response: if the key changes again or the
-    // field unmounts before this request settles, the loser's `.then`/`.catch`/
-    // `.finally` must not overwrite state a newer request already owns.
-    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(',');
-        apiClient.content
-            .getReferenceOptions(params)
-            .then((response) => {
-            if (!active)
-                return;
-            if (response.ok && response.data?.options) {
-                const mappedOptions = response.data.options.map((opt) => ({
-                    value: opt.id,
-                    label: opt.label,
-                }));
-                setOptions(mappedOptions);
-            }
-            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;
-        };
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- collections/entryTypes/displayField/branch are captured via fetchKey; re-listing them here would defeat the point of keying on the derived string
-    }, [needsFetch, fetchKey, retryCount, contextApiClient]);
-    const handleRetry = () => {
-        setLoading(true);
-        setError(null);
-        setRetryCount((count) => count + 1);
-    };
     const settled = !loading && !error;
+    // Stable between renders, as in ReferenceListField.
+    const renderOption = useMemo(() => referenceOptionRenderer(options), [options]);
+    const pickedOption = options.find((option) => option.value === normalizedValue);
+    const hidden = settled && pickedOption?.noindex ? pickedOption : undefined;
     // One label row for every state, so the comment popover in it survives loading and Retry.
-    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, ...(settled ? {} : groupDescriptionProps(inputId, description)), children: [_jsx(FieldLabel, { label: label, htmlFor: settled ? inputId : undefined, commentControl: commentControl }), loading ? (_jsxs(_Fragment, { children: [_jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(Loader, { size: "sm", "data-testid": `reference-loading-${dataCanopyField}` })] })) : error ? (_jsxs(_Fragment, { children: [_jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", title: "Error", "data-testid": `reference-error-${dataCanopyField}`, children: _jsxs(Stack, { gap: 4, children: [_jsx(Text, { size: "sm", children: error }), _jsx(Button, { variant: "light", onClick: handleRetry, "data-testid": `reference-retry-${dataCanopyField}`, children: "Retry" })] }) })] })) : multiple ? (_jsx(MultiSelect, { id: inputId, "aria-label": label, description: description, data: data, value: normalizedValue, readOnly: readOnly, rightSection: readOnly ? _jsx("span", {}) : undefined, onChange: (next) => {
-                    if (!readOnly)
-                        onChange(next);
-                }, searchable: true, placeholder: readOnly ? undefined : 'Select reference…', size: "sm" })) : (_jsx(Select, { id: inputId, "aria-label": label, description: description, data: data, value: normalizedValue, readOnly: readOnly, rightSection: readOnly ? _jsx("span", {}) : undefined, onChange: (next) => {
-                    if (!readOnly)
-                        onChange(next ?? '');
-                }, searchable: true, clearable: true, placeholder: readOnly ? undefined : 'Select reference…', size: "sm" }))] }));
+    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, ...(settled ? {} : groupDescriptionProps(inputId, description)), children: [_jsx(FieldLabel, { label: label, htmlFor: settled ? inputId : undefined, commentControl: commentControl }), loading ? (_jsxs(_Fragment, { children: [_jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(Loader, { size: "sm", "data-testid": `reference-loading-${dataCanopyField}` })] })) : error ? (_jsxs(_Fragment, { children: [_jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", title: "Error", "data-testid": `reference-error-${dataCanopyField}`, children: _jsxs(Stack, { gap: 4, children: [_jsx(Text, { size: "sm", children: error }), _jsx(Button, { variant: "light", onClick: retry, "data-testid": `reference-retry-${dataCanopyField}`, children: "Retry" })] }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Select, { id: inputId, "aria-label": label, description: description, data: data, renderOption: renderOption, inputContainer: (input) => hidden ? (_jsxs(Group, { gap: "xs", wrap: "nowrap", children: [_jsx("div", { style: { flex: 1, minWidth: 0 }, children: input }), _jsx(HiddenFromSearchBadge, {})] })) : (input), value: normalizedValue, readOnly: readOnly, rightSection: readOnly ? _jsx("span", {}) : undefined, onChange: (next) => {
+                            if (!readOnly)
+                                onChange(next ?? '');
+                        }, searchable: true, clearable: true, placeholder: readOnly ? undefined : 'Select reference…', size: "sm" }), hidden?.noindex && (_jsx(HiddenPicksNote, { picks: [{ label: hidden.label, fieldLabel: hidden.noindex.fieldLabel }] }))] }))] }));
 };

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

@@ -0,0 +1,41 @@
+import React from 'react';
+import type { ReferenceOptionSort } from '../../config/index.js';
+import { type ReferenceOption } from './use-reference-options.js';
+export interface ReferenceListFieldProps {
+    /** Base for the description's id. */
+    id: string;
+    label: string;
+    description?: string;
+    required?: boolean;
+    /** Offered as given; without them, options load from the API. */
+    options?: ReferenceOption[];
+    collections?: string[];
+    entryTypes?: string[];
+    displayField?: string;
+    branch?: string;
+    optionSort?: ReferenceOptionSort;
+    /** The stored items: ids, or a resolved read's `{ id, … }`. */
+    value: readonly unknown[];
+    /** Always given ids. */
+    onChange: (next: string[]) => void;
+    path: Array<string | number>;
+    /** The list's canopy path, which picks its comment control. */
+    canopyPath: string;
+    readOnly?: boolean;
+    /** Names the entry being edited; another entry starts with every row shut again. */
+    resetKey: string;
+    /** The most picks the list holds; the Add control gives way to a note at it. */
+    maxItems?: number;
+    /** The validation error on item `index`, if any. */
+    itemError?: (index: number) => string | undefined;
+    /** Called after Remove takes item `index` out, so the caller can offer Undo. */
+    onRemoved?: (index: number, id: string, title: string) => void;
+}
+/**
+ * A `list: true` reference field: one collapsible row per pick, in stored order, reordered by drag
+ * or the row menu. A row's body repoints that pick in place; an Add control under the rows appends
+ * and keeps focus, so several picks are several choices in a row. Neither control offers an entry
+ * another row holds, so no edit makes a duplicate. Comments attach to the whole field: a string
+ * item carries no item key for a thread to follow through a move.
+ */
+export declare const ReferenceListField: React.FC<ReferenceListFieldProps>;

package/dist/editor/fields/ReferenceListField.js

@@ -0,0 +1,139 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Alert, Button, Paper, Select, Skeleton, Stack, Text } from '@mantine/core';
+import { IconAlertCircle } from '@tabler/icons-react';
+import { useFieldCommentControl } from '../comments/field-comment-context.js';
+import { ExpandAllButton } from './ExpandAllButton.js';
+import { groupDescriptionProps } from './FieldDescription.js';
+import { FieldLabel } from './FieldLabel.js';
+import { ItemList } from './ItemList.js';
+import { useItemExpansion } from './item-expansion.js';
+import { useListItemKeys } from './list-item-keys.js';
+import { HIDDEN_FROM_SEARCH, HiddenPicksNote, referenceOptionRenderer, } from './reference-noindex.js';
+import { extractId, unlistedReferenceLabel, useReferenceOptions, } from './use-reference-options.js';
+const plural = (count, one, many) => (count === 1 ? one : many);
+/**
+ * A `list: true` reference field: one collapsible row per pick, in stored order, reordered by drag
+ * or the row menu. A row's body repoints that pick in place; an Add control under the rows appends
+ * and keeps focus, so several picks are several choices in a row. Neither control offers an entry
+ * another row holds, so no edit makes a duplicate. Comments attach to the whole field: a string
+ * item carries no item key for a thread to follow through a move.
+ */
+export const ReferenceListField = ({ id, label, description, required, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', optionSort, value, onChange, path, canopyPath, readOnly = false, resetKey, maxItems, itemError, onRemoved, }) => {
+    const commentControl = useFieldCommentControl(canopyPath);
+    const { options, loading, error, retry } = useReferenceOptions({
+        staticOptions,
+        collections,
+        entryTypes,
+        displayField,
+        branch,
+        optionSort,
+    });
+    const ids = value.map(extractId);
+    const keysFor = useListItemKeys();
+    const itemKeys = keysFor(ids, 'references');
+    // A collapsed row already names its entry; it opens only to swap that entry.
+    const expansion = useItemExpansion(itemKeys, resetKey, { rowsStartOpen: false });
+    const [announcement, setAnnouncement] = useState();
+    const [addSearch, setAddSearch] = useState('');
+    // The pick that reaches `maxItems` unmounts the focused Add control; its note takes focus instead.
+    const capNoteRef = useRef(null);
+    const focusCapNoteRef = useRef(false);
+    useEffect(() => {
+        if (!focusCapNoteRef.current)
+            return;
+        focusCapNoteRef.current = false;
+        capNoteRef.current?.focus();
+    });
+    const labels = new Map(options.map((option) => [option.value, option.label]));
+    // Until options settle, a title is unknown rather than unlisted, and after a failed load: either
+    // way the id is all there is to show (a Remove's Undo toast names it).
+    const titleOf = (index) => {
+        const itemId = ids[index];
+        if (!itemId)
+            return 'No entry picked';
+        return (labels.get(itemId) ??
+            (loading || error ? itemId : unlistedReferenceLabel(value[index], itemId)));
+    };
+    const picked = new Set(ids);
+    const hiddenField = new Map(options.flatMap((option) => option.noindex ? [[option.value, option.noindex.fieldLabel]] : []));
+    // Held back while options load: a stale list could name the wrong picks.
+    const hiddenPicks = loading || error
+        ? []
+        : [...picked].flatMap((pick) => {
+            const fieldLabel = hiddenField.get(pick);
+            return fieldLabel ? [{ label: labels.get(pick) ?? pick, fieldLabel }] : [];
+        });
+    // Stable between renders: a new `renderOption` makes Mantine drop the option that typing
+    // highlighted, so Enter after a search would add nothing.
+    const renderOption = useMemo(() => referenceOptionRenderer(loading || error ? [] : options), [options, loading, error]);
+    const atCap = maxItems !== undefined && ids.length >= maxItems;
+    /** Row `index`'s choices: every option no other row holds, plus its own pick. */
+    const rowOptions = (index) => {
+        const own = ids[index];
+        const elsewhere = new Set(ids.filter((_, i) => i !== index));
+        const offered = options.filter((option) => option.value === own || !elsewhere.has(option.value));
+        return own && !labels.has(own) ? [...offered, { value: own, label: titleOf(index) }] : offered;
+    };
+    const emit = (next) => {
+        if (!readOnly)
+            onChange(next);
+    };
+    const add = (pick) => {
+        if (picked.has(pick) || atCap)
+            return;
+        const count = ids.length + 1;
+        setAnnouncement({
+            message: `${labels.get(pick) ?? pick} added, position ${count} of ${count}.`,
+        });
+        setAddSearch('');
+        if (maxItems !== undefined && count >= maxItems)
+            focusCapNoteRef.current = true;
+        emit([...ids, pick]);
+    };
+    const capNote = maxItems === undefined
+        ? undefined
+        : ids.length > maxItems
+            ? `${ids.length} picked, but at most ${maxItems} ${plural(maxItems, 'is', 'are')} allowed. Remove ${ids.length - maxItems} to save.`
+            : `${ids.length} of ${maxItems} picked. Open a row to swap its entry, or remove one to add another.`;
+    return (_jsx(Paper, { withBorder: true, p: "md", shadow: "xs", ...groupDescriptionProps(id, description), role: "group", "aria-label": label, "data-removal-focus": true, tabIndex: -1, "data-canopy-field": canopyPath, "data-testid": `reference-list-${canopyPath}`, children: _jsxs(Stack, { gap: "sm", children: [_jsx(FieldLabel, { label: label, required: required, description: description, descriptionBaseId: id, commentControl: commentControl, actions: ids.length > 1 && _jsx(ExpandAllButton, { expansion: expansion }) }), error && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", title: "Couldn't load the entries to pick from", "data-testid": "reference-list-error", children: _jsxs(Stack, { gap: 4, align: "flex-start", children: [_jsx(Text, { size: "sm", children: error }), _jsx(Button, { variant: "light", size: "xs", onClick: retry, children: "Retry" })] }) })), _jsx(HiddenPicksNote, { picks: hiddenPicks }), _jsx(ItemList, { items: value, itemKeys: itemKeys, path: path, readOnly: readOnly, expansion: expansion, announcement: announcement, summarize: (_, idx) => loading
+                        ? { title: 'Loading…', pending: true }
+                        : {
+                            title: titleOf(idx),
+                            ...(!error &&
+                                hiddenField.has(ids[idx]) && {
+                                badge: { label: HIDDEN_FROM_SEARCH, color: 'yellow' },
+                            }),
+                        }, hasErrors: itemError ? (idx) => itemError(idx) !== undefined : undefined, onMove: (from, to) => {
+                        if (from === to || to < 0 || to >= ids.length)
+                            return;
+                        const next = [...ids];
+                        const [moved] = next.splice(from, 1);
+                        next.splice(to, 0, moved);
+                        emit(next);
+                    }, onRemove: (idx) => {
+                        if (readOnly)
+                            return;
+                        const title = titleOf(idx);
+                        emit(ids.filter((_, i) => i !== idx));
+                        onRemoved?.(idx, ids[idx], title);
+                    }, renderItem: (_, idx) => loading ? (_jsx(Skeleton, { height: 36 })) : (_jsx(Select, { label: "Entry", data: rowOptions(idx), renderOption: renderOption, value: ids[idx] || null, readOnly: readOnly, rightSection: readOnly ? _jsx("span", {}) : undefined, onChange: (next) => {
+                            if (!next || next === ids[idx])
+                                return;
+                            const updated = [...ids];
+                            updated[idx] = next;
+                            emit(updated);
+                        }, error: itemError?.(idx), 
+                        // No `selectFirstOptionOnChange` here: with the row's own title in the box every
+                        // option shows, so Enter would repoint the row to the first.
+                        searchable: true, allowDeselect: false, nothingFoundMessage: "No entries match", size: "sm", "data-testid": "reference-list-row-select" })) }), !loading && ids.length === 0 && (_jsx(Text, { size: "sm", c: "dimmed", children: readOnly ? 'Nothing picked.' : 'Nothing picked yet.' })), !readOnly &&
+                    (atCap ? (_jsx(Text, { ref: capNoteRef, tabIndex: -1, size: "sm", c: "dimmed", "data-testid": "reference-list-cap", children: capNote })) : loading ? (_jsx(Skeleton, { height: 36, "data-testid": "reference-list-add-pending" })) : error ? null : (_jsx(Select, { "aria-label": `Add to ${label}`, placeholder: "Search to add an entry", data: options.filter((option) => !picked.has(option.value)), renderOption: renderOption, value: null, searchValue: addSearch, onSearchChange: setAddSearch, onChange: (next) => {
+                            if (next)
+                                add(next);
+                        }, searchable: true, 
+                        // So typing part of a title and pressing Enter picks it.
+                        selectFirstOptionOnChange: true, nothingFoundMessage: options.length > 0 && options.every((option) => picked.has(option.value))
+                            ? 'Every entry is already picked'
+                            : 'No entries match', size: "sm", "data-testid": "reference-list-add" })))] }) }));
+};

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

@@ -15,6 +15,8 @@ export interface SelectFieldProps {
     dataCanopyField?: string;
     /** Shows the value without accepting edits. */
     readOnly?: boolean;
+    /** With `multiple`, the most values it holds; at it, the hint says why it takes no more. */
+    maxItems?: number;
 }
 export declare const SelectField: React.FC<SelectFieldProps>;
 export {};

package/dist/editor/fields/SelectField.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
 import { MultiSelect, Select, Stack, Text } from '@mantine/core';
+import { listFullReason } from '../copy.js';
 import { useFieldCommentControl } from '../comments/field-comment-context.js';
 import { FieldLabel } from './FieldLabel.js';
-export const SelectField = ({ id, label, description, options, value, onChange, multiple, placeholder = 'Select…', dataCanopyField, readOnly = false, }) => {
+export const SelectField = ({ id, label, description, options, value, onChange, multiple, placeholder = 'Select…', dataCanopyField, readOnly = false, maxItems, }) => {
     const normalizedValue = multiple
         ? Array.isArray(value)
             ? value
@@ -17,8 +18,10 @@ export const SelectField = ({ id, label, description, options, value, onChange,
     return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, children: [_jsx(FieldLabel, { label: label, htmlFor: inputId, commentControl: commentControl }), multiple ? (_jsx(MultiSelect, { id: inputId, "aria-label": label, description: description, data: options, value: normalizedValue, readOnly: readOnly, rightSection: readOnly ? _jsx("span", {}) : undefined, onChange: (next) => {
                     if (!readOnly)
                         onChange(next);
-                }, searchable: true, placeholder: readOnly ? undefined : placeholder, size: "sm" })) : (_jsx(Select, { id: inputId, "aria-label": label, description: description, data: options, value: normalizedValue, readOnly: readOnly, rightSection: readOnly ? _jsx("span", {}) : undefined, onChange: (next) => {
+                }, searchable: true, maxValues: maxItems, placeholder: readOnly ? undefined : placeholder, size: "sm" })) : (_jsx(Select, { id: inputId, "aria-label": label, description: description, data: options, value: normalizedValue, readOnly: readOnly, rightSection: readOnly ? _jsx("span", {}) : undefined, onChange: (next) => {
                     if (!readOnly)
                         onChange(next ?? '');
-                }, searchable: true, clearable: true, placeholder: readOnly ? undefined : placeholder, size: "sm" })), multiple && !readOnly && (_jsx(Text, { size: "xs", c: "dimmed", children: "Searchable multi-select; start typing to filter." }))] }));
+                }, searchable: true, clearable: true, placeholder: readOnly ? undefined : placeholder, size: "sm" })), multiple && !readOnly && (_jsx(Text, { size: "xs", c: "dimmed", children: maxItems !== undefined && normalizedValue.length >= maxItems
+                    ? listFullReason(maxItems)
+                    : 'Searchable multi-select; start typing to filter.' }))] }));
 };

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

@@ -8,12 +8,21 @@ export interface StringListFieldProps {
     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;
 }
+/**
+ * `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 declare const tagCap: (count: number, maxItems: number | undefined) => number | undefined;
+/** The field's description, ended as a sentence, then `hint`. */
+export declare const withHint: (description: string | undefined, hint: string) => string;
 /**
  * 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 declare const StringListField: React.FC<StringListFieldProps>;