canopycms 0.0.68-int.98 → 0.1.0

package/dist/editor/fields/ObjectListField.js

@@ -0,0 +1,57 @@
+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 { 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 { useFieldCommentControl } from '../comments/field-comment-context.js';
+import { groupDescriptionProps } from './FieldDescription.js';
+import { FieldLabel } from './FieldLabel.js';
+import { ExpandAllButton } from './ExpandAllButton.js';
+import { ItemList } from './ItemList.js';
+import { useItemExpansion } from './item-expansion.js';
+import { listItemSummary } from './list-item-title.js';
+/**
+ * A `list: true` object field: one collapsible row per item, titled from the item's content,
+ * holding the item's fields directly rather than in a second card.
+ */
+export const ObjectListField = ({ id, label, field, items, itemKeys, onChange, renderField, path, canopyPath, readOnly, resetKey, hasErrors, onRemoved, }) => {
+    const commentControl = useFieldCommentControl(canopyPath);
+    const expansion = useItemExpansion(itemKeys, resetKey);
+    const focusAfterRenderRef = useRef(null);
+    const insertAt = (index, item) => {
+        focusAfterRenderRef.current = index;
+        onChange([...items.slice(0, index), item, ...items.slice(index)]);
+    };
+    return (_jsx(Paper, { withBorder: true, p: "md", shadow: "xs", ...groupDescriptionProps(id, field.description), role: "group", "aria-label": label, "data-removal-focus": true, tabIndex: -1, children: _jsxs(Stack, { gap: "sm", children: [_jsx(FieldLabel, { label: label, required: field.required, description: field.description, descriptionBaseId: id, commentControl: commentControl, actions: items.length > 1 && _jsx(ExpandAllButton, { expansion: expansion }) }), _jsx(ItemList, { items: items, itemKeys: itemKeys, path: path, readOnly: readOnly, expansion: expansion, summarize: (item, idx) => listItemSummary(item, field, idx), hasErrors: hasErrors, focusAfterRenderRef: focusAfterRenderRef, onMove: (from, to) => {
+                        if (from === to || to < 0 || to >= items.length)
+                            return;
+                        const next = [...items];
+                        const [moved] = next.splice(from, 1);
+                        next.splice(to, 0, moved);
+                        onChange(next);
+                    }, onDuplicate: (idx) => 
+                    // Focus stays on the row's menu, which stands in for the item that acted. The copy
+                    // gets new keys, so no comment thread follows it.
+                    onChange([
+                        ...items.slice(0, idx + 1),
+                        withFreshItemKeys(field, structuredClone(items[idx])),
+                        ...items.slice(idx + 1),
+                    ]), onRemove: (idx) => {
+                        const item = items[idx];
+                        onChange(items.filter((_, i) => i !== idx));
+                        onRemoved?.(idx, item);
+                    }, renderItem: (item, idx) => {
+                        const itemPath = [...path, idx];
+                        const current = isPlainRecord(item) ? item : {};
+                        return field.fields.map((child) => {
+                            const childPath = [...itemPath, child.name];
+                            return (_jsx("div", { children: renderField(child, current[child.name], (next) => {
+                                    const nextItems = [...items];
+                                    nextItems[idx] = { ...current, [child.name]: next };
+                                    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'] }) }))] }) }));
+};

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

@@ -17,5 +17,7 @@ export interface ReferenceFieldProps {
     onChange: (value: string | string[]) => void;
     multiple?: boolean;
     dataCanopyField?: string;
+    /** Shows the value without accepting edits. */
+    readOnly?: boolean;
 }
 export declare const ReferenceField: React.FC<ReferenceFieldProps>;

package/dist/editor/fields/ReferenceField.js

@@ -1,13 +1,25 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { 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';
-export const ReferenceField = ({ id, label, description, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', value, onChange, multiple, dataCanopyField, }) => {
+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
@@ -32,8 +44,19 @@ export const ReferenceField = ({ id, label, description, options: staticOptions,
             ? value.map(extractId)
             : []
         : 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 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
@@ -101,11 +124,13 @@ export const ReferenceField = ({ id, label, description, options: staticOptions,
         setError(null);
         setRetryCount((count) => count + 1);
     };
-    if (loading) {
-        return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(Loader, { size: "sm", "data-testid": `reference-loading-${dataCanopyField}` })] }));
-    }
-    if (error) {
-        return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _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, { size: "xs", variant: "light", onClick: handleRetry, "data-testid": `reference-retry-${dataCanopyField}`, children: "Retry" })] }) })] }));
-    }
-    return (_jsx(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, children: multiple ? (_jsx(MultiSelect, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: "Select reference\u2026", size: "sm" })) : (_jsx(Select, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next ?? ''), searchable: true, clearable: true, placeholder: "Select reference\u2026", size: "sm" })) }));
+    const settled = !loading && !error;
+    // 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" }))] }));
 };

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

@@ -13,6 +13,8 @@ export interface SelectFieldProps {
     multiple?: boolean;
     placeholder?: string;
     dataCanopyField?: string;
+    /** Shows the value without accepting edits. */
+    readOnly?: boolean;
 }
 export declare const SelectField: React.FC<SelectFieldProps>;
 export {};

package/dist/editor/fields/SelectField.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
 import { MultiSelect, Select, Stack, Text } from '@mantine/core';
-export const SelectField = ({ id, label, description, options, value, onChange, multiple, placeholder = 'Select…', dataCanopyField, }) => {
+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, }) => {
     const normalizedValue = multiple
         ? Array.isArray(value)
             ? value
@@ -11,5 +13,12 @@ export const SelectField = ({ id, label, description, options, value, onChange,
             : '';
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, children: [multiple ? (_jsx(MultiSelect, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: placeholder, size: "sm" })) : (_jsx(Select, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next ?? ''), searchable: true, clearable: true, placeholder: placeholder, size: "sm" })), multiple && (_jsx(Text, { size: "xs", c: "dimmed", children: "Searchable multi-select; start typing to filter." }))] }));
+    const commentControl = useFieldCommentControl(dataCanopyField);
+    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) => {
+                    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." }))] }));
 };

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

@@ -6,11 +6,14 @@ export interface StringListFieldProps {
     value: string[];
     onChange: (value: string[]) => void;
     dataCanopyField?: string;
+    /** Shows the value without accepting edits. */
+    readOnly?: boolean;
 }
 /**
  * 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.
+ * 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.
  */
 export declare const StringListField: React.FC<StringListFieldProps>;

package/dist/editor/fields/StringListField.js

@@ -1,19 +1,33 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from 'react';
 import { TagsInput } from '@mantine/core';
+import { LabelledInput } from './FieldLabel.js';
+/** The field's description, ended as a sentence, then the hint that Enter adds. */
+const withEnterHint = (description) => {
+    const own = description?.trim();
+    if (!own)
+        return 'Press Enter to add.';
+    return `${/[.!?]$/.test(own) ? own : `${own}.`} Press Enter to add.`;
+};
 /**
  * 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.
+ * 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.
  */
-export const StringListField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
+export const StringListField = ({ id, label, description, value, onChange, dataCanopyField, readOnly = false, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(TagsInput, { id: inputId, label: label, description: description, value: value, size: "sm", onChange: onChange, 
-        // Faithful generic-list semantics, not tag ergonomics: no comma-splitting
-        // ("New York, NY" stays one item) and duplicates are legitimate list
-        // data — TagsInput's defaults would break both, so existing file data
-        // couldn't round-trip.
-        splitChars: [], allowDuplicates: true, "data-canopy-field": dataCanopyField }));
+    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) => {
+                if (!readOnly)
+                    onChange(next);
+            }, 
+            // Faithful generic-list semantics, not tag ergonomics: no comma-splitting
+            // ("New York, NY" stays one item) and duplicates are legitimate list
+            // data — TagsInput's defaults would break both, so existing file data
+            // couldn't round-trip.
+            splitChars: [], allowDuplicates: true, "data-canopy-field": dataCanopyField }) }));
 };

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

@@ -6,5 +6,7 @@ export interface TextFieldProps {
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;
+    /** Shows the value without accepting edits. */
+    readOnly?: boolean;
 }
 export declare const TextField: React.FC<TextFieldProps>;

package/dist/editor/fields/TextField.js

@@ -1,8 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from 'react';
 import { TextInput } from '@mantine/core';
-export const TextField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
+import { LabelledInput } from './FieldLabel.js';
+export const TextField = ({ id, label, description, value, onChange, dataCanopyField, readOnly = false, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(TextInput, { id: inputId, label: label, description: description, value: value, size: "sm", onChange: (e) => onChange(e.currentTarget.value), "data-canopy-field": dataCanopyField }));
+    return (_jsx(LabelledInput, { label: label, inputId: inputId, canopyPath: dataCanopyField, children: _jsx(TextInput, { id: inputId, description: description, value: value, size: "sm", readOnly: readOnly, onChange: (e) => {
+                if (!readOnly)
+                    onChange(e.currentTarget.value);
+            }, "data-canopy-field": dataCanopyField }) }));
 };

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

@@ -7,5 +7,7 @@ export interface ToggleFieldProps {
     onChange: (value: boolean) => void;
     dataCanopyField?: string;
     testId?: string;
+    /** Shows the value without accepting edits. */
+    readOnly?: boolean;
 }
 export declare const ToggleField: React.FC<ToggleFieldProps>;

package/dist/editor/fields/ToggleField.js

@@ -1,11 +1,16 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
-import { Stack, Switch } from '@mantine/core';
+import { Group, Stack, Switch, Text } from '@mantine/core';
+import { useFieldCommentControl } from '../comments/field-comment-context.js';
 import { FieldDescription, fieldDescriptionId } from './FieldDescription.js';
-export const ToggleField = ({ id, label, description, value, onChange, dataCanopyField, testId, }) => {
+export const ToggleField = ({ id, label, description, value, onChange, dataCanopyField, testId, readOnly = false, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
+    const commentControl = useFieldCommentControl(dataCanopyField);
     // A Switch's `description` sits inside its <label> and so joins the accessible name;
     // rendering it as a sibling keeps the name to the label alone.
-    return (_jsxs(Stack, { gap: 4, children: [_jsx(Switch, { id: inputId, label: label, "aria-describedby": description ? fieldDescriptionId(inputId) : undefined, checked: value, onChange: (e) => onChange(e.currentTarget.checked), size: "md", "data-canopy-field": dataCanopyField, wrapperProps: testId ? { 'data-testid': testId } : undefined }), _jsx(FieldDescription, { baseId: inputId, description: description })] }));
+    return (_jsxs(Stack, { gap: 4, children: [_jsxs(Group, { gap: "sm", wrap: "nowrap", children: [_jsx(Switch, { id: inputId, label: label, "aria-describedby": description ? fieldDescriptionId(inputId) : undefined, checked: value, "aria-readonly": readOnly || undefined, styles: readOnly ? { track: { cursor: 'default' }, input: { cursor: 'default' } } : undefined, onChange: (e) => {
+                            if (!readOnly)
+                                onChange(e.currentTarget.checked);
+                        }, size: "sm", "data-canopy-field": dataCanopyField, wrapperProps: testId ? { 'data-testid': testId } : undefined }), commentControl, readOnly && (_jsx(Text, { size: "sm", c: "dimmed", "data-testid": testId ? `${testId}-value` : undefined, children: value ? 'On' : 'Off' }))] }), _jsx(FieldDescription, { baseId: inputId, description: description })] }));
 };

package/dist/editor/fields/entry-link/InsertEntryLink.d.ts

@@ -5,7 +5,7 @@
  */
 import React from 'react';
 interface InsertEntryLinkProps {
-    /** MDXEditor's insertMarkdown function, obtained via usePublisher(insertMarkdown$) */
+    /** Inserts the link's markdown into the editor (MarkdownField's `handleInsert`). */
     onInsert: (markdown: string) => void;
 }
 export declare const InsertEntryLink: React.FC<InsertEntryLinkProps>;

package/dist/editor/fields/entry-link/InsertEntryLink.js

@@ -44,7 +44,7 @@ export const InsertEntryLink = ({ onInsert }) => {
         setOpened(false);
         setSearch('');
     };
-    return (_jsxs(_Fragment, { children: [_jsx(ActionIcon, { variant: "subtle", size: "sm", color: "gray", title: "Insert entry link", "data-testid": "insert-entry-link-button", onClick: () => setOpened(true), children: _jsx(IconFileSymlink, { size: 16 }) }), _jsx(Modal, { opened: opened, onClose: () => {
+    return (_jsxs(_Fragment, { children: [_jsx(ActionIcon, { variant: "subtle", color: "gray", title: "Insert entry link", "data-testid": "insert-entry-link-button", onClick: () => setOpened(true), children: _jsx(IconFileSymlink, { size: 16 }) }), _jsx(Modal, { opened: opened, onClose: () => {
                     setOpened(false);
                     setSearch('');
                 }, title: "Link to Entry", size: "md", children: _jsx(Stack, { gap: "sm", children: _jsxs(Combobox, { store: combobox, onOptionSubmit: (val) => {

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

@@ -0,0 +1,9 @@
+/**
+ * A form-wide "Expand all" or "Collapse all". `seq` grows with each press, so pressing the same
+ * one twice still counts; a list applies only presses made while it is mounted.
+ */
+export interface FormExpansionCommand {
+    seq: number;
+    expanded: boolean;
+}
+export declare const FormExpansionContext: import("react").Context<FormExpansionCommand | undefined>;

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

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const FormExpansionContext = createContext(undefined);

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

@@ -0,0 +1,15 @@
+export interface ItemExpansion {
+    isExpanded: (key: string) => boolean;
+    setExpanded: (key: string, expanded: boolean) => void;
+    setAll: (expanded: boolean) => void;
+    /** True when every row is expanded; false for an empty list. */
+    allExpanded: boolean;
+}
+/**
+ * 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.
+ */
+export declare function useItemExpansion(itemKeys: readonly string[], resetKey: string): ItemExpansion;

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

@@ -0,0 +1,60 @@
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { FormExpansionContext } from './form-expansion.js';
+/** Up to this many rows all start expanded; a longer list starts with only its first open. */
+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.
+ */
+export function useItemExpansion(itemKeys, resetKey) {
+    const [toggled, setToggled] = useState(() => ({
+        resetKey,
+        open: new Map(),
+    }));
+    // Decided once per key, the first time it renders, and kept until `resetKey` changes.
+    const defaults = useRef({
+        resetKey,
+        open: new Map(),
+        started: false,
+    });
+    if (defaults.current.resetKey !== resetKey) {
+        defaults.current = { resetKey, open: new Map(), started: false };
+    }
+    const firstPopulation = !defaults.current.started && itemKeys.length > 0;
+    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);
+    });
+    if (itemKeys.length > 0)
+        defaults.current.started = true;
+    const explicit = toggled.resetKey === resetKey ? toggled.open : undefined;
+    const isExpanded = (key) => explicit?.get(key) ?? defaults.current.open.get(key) ?? true;
+    const setExpanded = useCallback((key, expanded) => setToggled((prev) => {
+        const open = new Map(prev.resetKey === resetKey ? prev.open : undefined);
+        open.set(key, expanded);
+        return { resetKey, open };
+    }), [resetKey]);
+    const setAll = (expanded) => setToggled(() => ({ resetKey, open: new Map(itemKeys.map((key) => [key, expanded])) }));
+    const command = useContext(FormExpansionContext);
+    const appliedSeq = useRef(command?.seq);
+    const keysRef = useRef(itemKeys);
+    useEffect(() => {
+        keysRef.current = itemKeys;
+    });
+    useEffect(() => {
+        if (!command || command.seq === appliedSeq.current)
+            return;
+        appliedSeq.current = command.seq;
+        setToggled({ resetKey, open: new Map(keysRef.current.map((key) => [key, command.expanded])) });
+    }, [command, resetKey]);
+    return {
+        isExpanded,
+        setExpanded,
+        setAll,
+        allExpanded: itemKeys.length > 0 && itemKeys.every(isExpanded),
+    };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 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`.
+ */
+export declare function useListItemKeys(): (items: readonly unknown[], listPath: string) => string[];

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

@@ -0,0 +1,50 @@
+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`.
+ */
+export function useListItemKeys() {
+    const listItemKeys = useRef(new WeakMap());
+    const lastListKeys = useRef(new Map());
+    const nextListItemKey = useRef(0);
+    return (items, listPath) => {
+        const previous = lastListKeys.current.get(listPath);
+        const occurrences = new Map();
+        for (const item of items) {
+            if (typeof item === 'object' && item !== null) {
+                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;
+        const claimed = new Set();
+        const keys = items.map((item) => {
+            const own = single(item) ? listItemKeys.current.get(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.
+        const resolved = keys.map((key, idx) => {
+            if (key !== undefined)
+                return key;
+            let next = previous?.length === items.length ? 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);
+            return next;
+        });
+        lastListKeys.current.set(listPath, resolved);
+        return resolved;
+    };
+}

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

@@ -0,0 +1,20 @@
+import type { FieldConfig, ObjectFieldConfig } from '../../config/index.js';
+/**
+ * What an object-list item is called: its `itemTitleField` value when that is a non-blank
+ * string or a number, else its first non-blank single-line text field, else undefined.
+ */
+export declare const listItemTitle: (item: unknown, objectField: Pick<ObjectFieldConfig, "fields" | "itemTitleField">) => string | undefined;
+type ItemNaming = Pick<ObjectFieldConfig, 'fields' | 'itemTitleField' | 'itemLabel'>;
+/** An object-list item's card heading: its title, else its positional title (1-based). */
+export declare const listItemHeading: (item: unknown, objectField: ItemNaming, index: number) => string;
+/**
+ * The second value a collapsed row shows beside its title: the first non-blank single-line text
+ * field other than the one `exclude` names, so a row never repeats its title.
+ */
+export declare const listItemSecondary: (item: unknown, fields: readonly FieldConfig[], exclude?: string) => string | undefined;
+/** A collapsed object-list row's title and secondary value. */
+export declare const listItemSummary: (item: unknown, objectField: ItemNaming, index: number) => {
+    title: string;
+    secondary?: string;
+};
+export {};

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

@@ -0,0 +1,85 @@
+const MAX_TITLE_LENGTH = 60;
+const shorten = (text) => text.length > MAX_TITLE_LENGTH ? `${text.slice(0, MAX_TITLE_LENGTH - 1)}…` : text;
+/** The item's own fields, with inline groups opened up, since groups are transparent to values. */
+const flattenFields = (fields) => fields.flatMap((f) => (f.type === 'group' && 'fields' in f ? flattenFields(f.fields) : [f]));
+const asRecord = (item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? item
+    : undefined;
+/** A value worth showing on one line: a non-blank string's first line, or a finite number. */
+const shownText = (raw) => {
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return String(raw);
+    if (typeof raw === 'string' && raw.trim() !== '')
+        return shorten(raw.trim().split('\n')[0]);
+    return undefined;
+};
+/** A select's value as its option's label, which is what an editor picked it by. */
+const optionLabel = (field, value) => {
+    const option = (field.options ?? []).find((o) => (typeof o === 'string' ? o : o.value) === value);
+    return option === undefined || typeof option === 'string' ? value : option.label;
+};
+/** The item's single-line text fields, in schema order: strings, numbers and single selects. */
+const textFields = (fields) => flattenFields(fields).filter((f) => (f.type === 'string' || f.type === 'number' || f.type === 'select') && !f.list);
+/**
+ * Which field titles an object-list item, and its text: its `itemTitleField` value when that is
+ * a non-blank string or a number, else its first non-blank single-line string field.
+ */
+const titleSource = (record, objectField) => {
+    const named = objectField.itemTitleField;
+    const raw = named ? record[named] : undefined;
+    if (named && typeof raw === 'number' && Number.isFinite(raw))
+        return { name: named, text: String(raw) };
+    if (named && typeof raw === 'string' && raw.trim() !== '') {
+        return { name: named, text: shorten(raw.trim()) };
+    }
+    for (const f of flattenFields(objectField.fields)) {
+        if (f.type !== 'string' || f.list)
+            continue;
+        const value = record[f.name];
+        if (typeof value === 'string' && value.trim() !== '') {
+            return { name: f.name, text: shorten(value.trim()) };
+        }
+    }
+    return undefined;
+};
+/**
+ * What an object-list item is called: its `itemTitleField` value when that is a non-blank
+ * string or a number, else its first non-blank single-line text field, else undefined.
+ */
+export const listItemTitle = (item, objectField) => {
+    const record = asRecord(item);
+    return record ? titleSource(record, objectField)?.text : undefined;
+};
+/** What an untitled item is called by position: "Item 3", or "Team member 3" from `itemLabel`. */
+const positionalTitle = (objectField, index) => {
+    const noun = objectField.itemLabel ?? 'item';
+    return `${noun.charAt(0).toUpperCase()}${noun.slice(1)} ${index + 1}`;
+};
+/** An object-list item's card heading: its title, else its positional title (1-based). */
+export const listItemHeading = (item, objectField, index) => listItemTitle(item, objectField) ?? positionalTitle(objectField, index);
+/**
+ * The second value a collapsed row shows beside its title: the first non-blank single-line text
+ * field other than the one `exclude` names, so a row never repeats its title.
+ */
+export const listItemSecondary = (item, fields, exclude) => {
+    const record = asRecord(item);
+    if (!record)
+        return undefined;
+    for (const f of textFields(fields)) {
+        if (f.name === exclude)
+            continue;
+        const text = shownText(f.type === 'select' ? optionLabel(f, record[f.name]) : record[f.name]);
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+};
+/** A collapsed object-list row's title and secondary value. */
+export const listItemSummary = (item, objectField, index) => {
+    const record = asRecord(item);
+    const source = record ? titleSource(record, objectField) : undefined;
+    return {
+        title: source?.text ?? positionalTitle(objectField, index),
+        secondary: listItemSecondary(item, objectField.fields, source?.name),
+    };
+};

package/dist/editor/fields/markdown-export-options.d.ts

@@ -0,0 +1,2 @@
+import type { ToMarkdownOptions } from '@mdxeditor/editor';
+export declare const MARKDOWN_EXPORT_OPTIONS: ToMarkdownOptions;

package/dist/editor/fields/markdown-export-options.js

@@ -0,0 +1,8 @@
+// Prettier's markers. The prop replaces MDXEditor's defaults, so `listItemIndent` is restated.
+export const MARKDOWN_EXPORT_OPTIONS = {
+    listItemIndent: 'one',
+    bullet: '-',
+    emphasis: '_',
+    strong: '*',
+    rule: '-',
+};

package/dist/editor/fields/markdown-fidelity-visitors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MarkdownField's MDXEditor visitors for markdown its own import and export would change the
+ * meaning of: an ordered list's `start`, a link inside a formatted span, an auto-link inside code,
+ * and the code spans either side of one. MDXEditor is passed in, as `mdx-jsx-support.tsx`
+ * explains.
+ */
+import type * as MdxEditor from '@mdxeditor/editor';
+type MdxEditorModule = typeof MdxEditor;
+/** Creates the plugin from MDXEditor's exports; call once per load of MDXEditor. */
+export declare function createMarkdownFidelityPlugin(mdx: MdxEditorModule): () => MdxEditor.RealmPlugin;
+export {};