canopycms 0.4.0 → 0.5.0

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

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;