canopycms 0.0.67 → 0.0.68-int.101

package/dist/editor/fields/InlineGroupField.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
 import { Paper, Stack, Text } from '@mantine/core';
 import { formatCanopyPath } from '../canopy-path.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 export const InlineGroupField = ({ label, description, fields, value, onChange, renderField, path, }) => {
-    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [(label || description) && (_jsxs(Stack, { gap: 2, children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label })), description && (_jsx(Text, { size: "xs", c: "dimmed", children: description }))] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
+    const descriptionBaseId = useId();
+    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", shadow: "xs", ...groupDescriptionProps(descriptionBaseId, description), children: _jsxs(Stack, { gap: "sm", children: [(label || description) && (_jsxs(Stack, { gap: 2, children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label })), _jsx(FieldDescription, { baseId: descriptionBaseId, description: description })] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
                         // Nested inline groups are also transparent — pass the same parent value/onChange
                         if (field.type === 'group') {
                             const childGroup = field;

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface MarkdownFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;

package/dist/editor/fields/MarkdownField.js

@@ -1,16 +1,21 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { Suspense, useId, useRef, useCallback, useEffect } from 'react';
-import { Text, Textarea } from '@mantine/core';
+import React, { Suspense, useId, useRef, useCallback, useEffect, useState } from 'react';
+import { Alert, Button, Group, Text, Textarea } from '@mantine/core';
 import { InsertEntryLink } from './entry-link/index.js';
 import { MdxImageDialog } from './MdxImageDialog.js';
-import { useApiClient } from '../context/index.js';
+import { useApiClient, useAssetContext } from '../context/index.js';
+import { editorImageSrc } from '../media/editor-image-src.js';
 import { uploadAsset } from '../media/upload-asset.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 const MDXEditorLazy = React.lazy(async () => {
-    const [{ MDXEditor }, { headingsPlugin, listsPlugin, quotePlugin, thematicBreakPlugin, markdownShortcutPlugin, linkPlugin, linkDialogPlugin, imagePlugin, tablePlugin, toolbarPlugin, codeBlockPlugin, codeMirrorPlugin, BoldItalicUnderlineToggles, BlockTypeSelect, ListsToggle, CreateLink, InsertImage, InsertTable, InsertThematicBreak, CodeToggle, InsertCodeBlock, UndoRedo, Separator, insertMarkdown$, usePublisher, useCellValues, saveImage$, closeImageDialog$, imageDialogState$, },] = await Promise.all([import('@mdxeditor/editor'), import('@mdxeditor/editor')]);
-    const EntryLinkToolbarButton = () => {
+    const [{ MDXEditor, headingsPlugin, listsPlugin, quotePlugin, thematicBreakPlugin, markdownShortcutPlugin, linkPlugin, linkDialogPlugin, imagePlugin, tablePlugin, toolbarPlugin, codeBlockPlugin, codeMirrorPlugin, BoldItalicUnderlineToggles, BlockTypeSelect, ListsToggle, CreateLink, InsertImage, InsertTable, InsertThematicBreak, CodeToggle, InsertCodeBlock, UndoRedo, Separator, insertMarkdown$, usePublisher, useCellValues, saveImage$, closeImageDialog$, imageDialogState$, activeEditor$, $isImageNode, 
+    // MDXEditor's own lexical instance: lexical keeps the active editor state per module, so
+    // a separately resolved copy would throw inside this editor's `read()`.
+    lexical: { $getNodeByKey }, }, { mdxJsxPlugins },] = await Promise.all([import('@mdxeditor/editor'), import('./mdx-jsx-support.js')]);
+    const EntryLinkToolbarButton = ({ onInsert }) => {
         const insertMarkdown = usePublisher(insertMarkdown$);
-        return _jsx(InsertEntryLink, { onInsert: insertMarkdown });
+        return (_jsx(InsertEntryLink, { onInsert: (markdown) => onInsert(() => insertMarkdown(markdown), markdown) }));
     };
     /**
      * Bridges mdxeditor's realm cells (reachable only once this lazy chunk has
@@ -19,13 +24,27 @@ const MDXEditorLazy = React.lazy(async () => {
      * `EntryLinkToolbarButton` above.
      */
     const MdxImageDialogBridge = () => {
-        const [state] = useCellValues(imageDialogState$);
+        const [state, editor] = useCellValues(imageDialogState$, activeEditor$);
         const saveImage = usePublisher(saveImage$);
         const closeImageDialog = usePublisher(closeImageDialog$);
-        return _jsx(MdxImageDialog, { state: state, onSave: saveImage, onClose: closeImageDialog });
+        // With an `imagePreviewHandler`, MDXEditor seeds an edit dialog with the src the node was
+        // first rendered with, not its current one, so saving after a src change would revert it.
+        // Read the node's live src from the same editor `saveImage$` writes through.
+        const liveState = React.useMemo(() => {
+            if (state.type !== 'editing' || !editor)
+                return state;
+            const src = editor.getEditorState().read(() => {
+                const node = $getNodeByKey(state.nodeKey);
+                return $isImageNode(node) ? node.getSrc() : undefined;
+            });
+            return src === undefined
+                ? state
+                : { ...state, initialValues: { ...state.initialValues, src } };
+        }, [state, editor]);
+        return _jsx(MdxImageDialog, { state: liveState, onSave: saveImage, onClose: closeImageDialog });
     };
-    const WrappedEditor = ({ markdown, onChange, editorRef, imageUploadHandler }) => {
-        return (_jsx(MDXEditor, { ref: editorRef, markdown: markdown, onChange: onChange, plugins: [
+    const WrappedEditor = ({ markdown, onChange, onError, onInsert, editorRef, imageUploadHandler, imagePreviewHandler, }) => {
+        return (_jsx(MDXEditor, { ref: editorRef, markdown: markdown, onChange: onChange, onError: onError, plugins: [
                 headingsPlugin(),
                 listsPlugin(),
                 quotePlugin(),
@@ -33,8 +52,13 @@ const MDXEditorLazy = React.lazy(async () => {
                 markdownShortcutPlugin(),
                 linkPlugin(),
                 linkDialogPlugin(),
-                imagePlugin({ imageUploadHandler, ImageDialog: MdxImageDialogBridge }),
+                imagePlugin({
+                    imageUploadHandler,
+                    imagePreviewHandler,
+                    ImageDialog: MdxImageDialogBridge,
+                }),
                 tablePlugin(),
+                ...mdxJsxPlugins(),
                 codeBlockPlugin({ defaultCodeBlockLanguage: '' }),
                 codeMirrorPlugin({
                     codeBlockLanguages: {
@@ -53,7 +77,7 @@ const MDXEditorLazy = React.lazy(async () => {
                     },
                 }),
                 toolbarPlugin({
-                    toolbarContents: () => (_jsxs(_Fragment, { children: [_jsx(UndoRedo, {}), _jsx(Separator, {}), _jsx(BoldItalicUnderlineToggles, {}), _jsx(CodeToggle, {}), _jsx(Separator, {}), _jsx(BlockTypeSelect, {}), _jsx(Separator, {}), _jsx(ListsToggle, {}), _jsx(Separator, {}), _jsx(CreateLink, {}), _jsx(EntryLinkToolbarButton, {}), _jsx(InsertImage, {}), _jsx(InsertTable, {}), _jsx(InsertThematicBreak, {}), _jsx(InsertCodeBlock, {})] })),
+                    toolbarContents: () => (_jsxs(_Fragment, { children: [_jsx(UndoRedo, {}), _jsx(Separator, {}), _jsx(BoldItalicUnderlineToggles, {}), _jsx(CodeToggle, {}), _jsx(Separator, {}), _jsx(BlockTypeSelect, {}), _jsx(Separator, {}), _jsx(ListsToggle, {}), _jsx(Separator, {}), _jsx(CreateLink, {}), _jsx(EntryLinkToolbarButton, { onInsert: onInsert }), _jsx(InsertImage, {}), _jsx(InsertTable, {}), _jsx(InsertThematicBreak, {}), _jsx(InsertCodeBlock, {})] })),
                 }),
             ], contentEditableClassName: "canopy-mdx-content" }));
     };
@@ -92,14 +116,31 @@ const EditorContentStyles = () => (_jsx("style", { children: `
     .canopy-mdx-content p { margin: 0.75em 0; }
     .canopy-mdx-content a { color: var(--mantine-color-blue-6, #228be6); text-decoration: underline; }
     .canopy-mdx-content img { max-width: 100%; height: auto; }
+    .canopy-mdx-content .canopy-mdx-jsx {
+      border: 1px dashed var(--mantine-color-gray-4, #ced4da);
+      border-radius: 4px;
+      padding: 2px 8px;
+      margin: 0.5em 0;
+    }
+    .canopy-mdx-content .canopy-mdx-jsx-inline { display: inline-block; margin: 0 2px; }
+    .canopy-mdx-content .canopy-mdx-jsx-tag {
+      font-family: var(--mantine-font-family-monospace, monospace);
+      font-size: 0.8em;
+      color: var(--mantine-color-gray-6, #868e96);
+    }
   ` }));
 const FallbackTextarea = ({ value, onChange, }) => (_jsx(Textarea, { value: value, onChange: (e) => onChange(e.currentTarget.value), placeholder: "Loading markdown editor...", autosize: true, minRows: 6, size: "sm", readOnly: true }));
-export const MarkdownField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const MarkdownField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const editorRef = useRef(null);
     const lastExternalValue = useRef(value);
+    const lastRejectedSource = useRef(null);
+    const pendingInsert = useRef(null);
     const apiClient = useApiClient();
+    const [mode, setMode] = useState({ kind: 'rich' });
+    const [rejectedInsert, setRejectedInsert] = useState(null);
+    const [editorGeneration, setEditorGeneration] = useState(0);
     // Drives both MDXEditor's drag/drop/paste upload and the custom image
     // dialog's Upload tab via the same presign/finalize-or-proxied pipeline
     // (media/upload-asset.ts). Memoized on the API client (itself memoized by
@@ -108,16 +149,70 @@ export const MarkdownField = ({ id, label, value, onChange, dataCanopyField, })
         const asset = await uploadAsset(apiClient, file);
         return asset.src;
     }, [apiClient]);
-    // Sync external value changes into the editor (e.g., undo, reset, load)
+    // MDXEditor displays each body image at whatever this resolves; the markdown keeps its src.
+    const { baseUrl: assetBaseUrl } = useAssetContext();
+    const imagePreviewHandler = useCallback(async (src) => editorImageSrc(src, assetBaseUrl), [assetBaseUrl]);
+    // Sync external value changes into the editor, recording them even while none
+    // is mounted, so a later return to an earlier value is still a change.
     useEffect(() => {
-        if (value !== lastExternalValue.current && editorRef.current) {
-            editorRef.current.setMarkdown(value);
-            lastExternalValue.current = value;
-        }
+        if (value === lastExternalValue.current)
+            return;
+        lastExternalValue.current = value;
+        editorRef.current?.setMarkdown(value);
     }, [value]);
-    const handleChange = useCallback((newValue) => {
+    const emitChange = useCallback((newValue) => {
         lastExternalValue.current = newValue;
+        setRejectedInsert(null);
         onChange(newValue);
     }, [onChange]);
-    return (_jsxs("div", { id: inputId, "data-canopy-field": dataCanopyField, className: "canopy-markdown-field", children: [label && (_jsx(Text, { size: "sm", fw: 500, mb: 4, children: label })), _jsx(EditorContentStyles, {}), _jsx("div", { style: editorWrapperStyle, children: _jsx(Suspense, { fallback: _jsx(FallbackTextarea, { value: value, onChange: onChange }), children: _jsx(MDXEditorLazy, { markdown: value, onChange: handleChange, editorRef: editorRef, imageUploadHandler: imageUploadHandler }) }) })] }));
+    // Dropped: MDXEditor's re-serialization of the document it was mounted with
+    // (flagged `initialMarkdownNormalize`; it would mark an unedited entry
+    // modified), and inserted markdown it rejected, which it emits as if that
+    // snippet were the whole document.
+    const handleEditorChange = useCallback((newValue, initialMarkdownNormalize) => {
+        if (initialMarkdownNormalize || newValue === lastRejectedSource.current)
+            return;
+        emitChange(newValue);
+    }, [emitChange]);
+    // MDXEditor reports a rejected insert synchronously, inside insertMarkdown
+    // (with no selection it imports nothing, and reports nothing).
+    const handleInsert = useCallback((insert, markdown) => {
+        pendingInsert.current = markdown;
+        try {
+            insert();
+        }
+        finally {
+            pendingInsert.current = null;
+        }
+    }, []);
+    // MDXEditor can report the error while rendering (it imports as it is
+    // created), hence the microtask. Any rejection outside an insert is the
+    // document, this render's `value`: MDXEditor is created from it, and gets
+    // this handler again before the sync effect hands it a later value. `source`
+    // can't identify it, because MDXEditor trims the document it mounts with.
+    // Either way MDXEditor emits no further edits until an import succeeds, so a
+    // rejected insert remounts it from the unchanged document.
+    const handleEditorError = useCallback(({ error, source }) => {
+        lastRejectedSource.current = source;
+        const isInsert = pendingInsert.current !== null && source === pendingInsert.current;
+        queueMicrotask(() => {
+            if (isInsert) {
+                setRejectedInsert(error);
+                setEditorGeneration((n) => n + 1);
+            }
+            else {
+                setMode({ kind: 'source', reason: error, failedValue: value });
+            }
+        });
+    }, [value]);
+    // Edits in the fallback stay in it: the edited text is no more likely to load.
+    const handleSourceChange = useCallback((newValue) => {
+        setMode((current) => current.kind === 'source' && current.reason !== null
+            ? { ...current, failedValue: newValue }
+            : current);
+        emitChange(newValue);
+    }, [emitChange]);
+    // A fallback holds only for the value MDXEditor rejected.
+    const showSource = mode.kind === 'source' && (mode.reason === null || mode.failedValue === value);
+    return (_jsxs("div", { id: inputId, "data-canopy-field": dataCanopyField, className: "canopy-markdown-field", ...groupDescriptionProps(inputId, description), children: [_jsxs(Group, { justify: "space-between", align: "flex-end", mb: 4, wrap: "nowrap", children: [label ? (_jsx(Text, { size: "sm", fw: 500, children: label })) : (_jsx("span", {})), _jsx(Button, { variant: "subtle", size: "compact-xs", "data-testid": "markdown-mode-toggle", onClick: () => setMode(showSource ? { kind: 'rich' } : { kind: 'source', reason: null }), children: showSource ? 'Rich text' : 'Edit source' })] }), _jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(EditorContentStyles, {}), showSource ? (_jsxs(_Fragment, { children: [mode.kind === 'source' && mode.reason !== null && (_jsxs(Alert, { color: "yellow", variant: "light", mb: "xs", "data-testid": "markdown-source-fallback", children: [_jsx(Text, { size: "sm", children: "The rich-text editor can't show this content, so it is open as source. Your edits here are saved as usual." }), _jsx(Text, { size: "xs", c: "dimmed", mt: 4, children: mode.reason })] })), _jsx(Textarea, { value: value, onChange: (e) => handleSourceChange(e.currentTarget.value), "aria-label": label ? `${label} (source)` : 'Markdown source', "data-testid": "markdown-source-editor", autosize: true, minRows: 10, size: "sm", styles: { input: { fontFamily: 'var(--mantine-font-family-monospace)' } } })] })) : (_jsxs("div", { style: editorWrapperStyle, children: [rejectedInsert !== null && (_jsxs(Alert, { color: "yellow", variant: "light", mb: "xs", withCloseButton: true, onClose: () => setRejectedInsert(null), "data-testid": "markdown-insert-rejected", children: [_jsx(Text, { size: "sm", children: "The rich-text editor can't show what was inserted, so nothing was added." }), _jsx(Text, { size: "xs", c: "dimmed", mt: 4, children: rejectedInsert })] })), _jsx(Suspense, { fallback: _jsx(FallbackTextarea, { value: value, onChange: onChange }), children: _jsx(MDXEditorLazy, { markdown: value, onChange: handleEditorChange, onError: handleEditorError, onInsert: handleInsert, editorRef: editorRef, imageUploadHandler: imageUploadHandler, imagePreviewHandler: imagePreviewHandler }, editorGeneration) })] }))] }));
 };

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface NumberFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: number | undefined;
     onChange: (value: number | undefined) => void;
     dataCanopyField?: string;

package/dist/editor/fields/NumberField.js

@@ -27,14 +27,14 @@ const toNumericValue = (raw) => {
  * would silently store `0.5` after the second keystroke. See
  * NumberField.test.tsx's keystroke matrix.
  */
-export const NumberField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const NumberField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const [inputValue, setInputValue] = useState(value ?? '');
     // Shows the in-progress text only while it still matches the parent's
     // value; once the parent's value diverges (load, discard, reload), that value wins.
     const displayValue = toNumericValue(inputValue) === value ? inputValue : (value ?? '');
-    return (_jsx(NumberInput, { id: inputId, label: label, value: displayValue, size: "sm", onChange: (next) => {
+    return (_jsx(NumberInput, { id: inputId, label: label, description: description, value: displayValue, size: "sm", onChange: (next) => {
             setInputValue(next);
             onChange(toNumericValue(next));
         }, "data-canopy-field": dataCanopyField }));

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface NumberListFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: number[];
     onChange: (value: number[]) => void;
     dataCanopyField?: string;

package/dist/editor/fields/NumberListField.js

@@ -27,11 +27,11 @@ 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, value, onChange, dataCanopyField, }) => {
+export const NumberListField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const [rejected, setRejected] = useState([]);
-    return (_jsx(TagsInput, { id: inputId, label: label, value: value.map(String), size: "sm", error: rejected.length > 0
+    return (_jsx(TagsInput, { id: inputId, label: label, description: description, value: value.map(String), size: "sm", error: rejected.length > 0
             ? `Not ${rejected.length === 1 ? 'a number' : 'numbers'}: ${rejected.join(', ')}`
             : undefined, onChange: (next) => {
             const parsed = [];

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

@@ -3,6 +3,7 @@ import type { FieldConfig } from '../../config/index.js';
 export type RenderField = (field: FieldConfig, value: unknown, onChange: (v: unknown) => void, path: Array<string | number>) => React.ReactNode;
 export interface ObjectFieldProps {
     label?: string;
+    description?: string;
     fields: FieldConfig[];
     value: Record<string, unknown> | undefined;
     onChange: (value: Record<string, unknown>) => void;

package/dist/editor/fields/ObjectField.js

@@ -1,9 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
 import { Button, Group, Paper, Stack, Text } from '@mantine/core';
 import { formatCanopyPath } from '../canopy-path.js';
-export const ObjectField = ({ label, fields, value, onChange, renderField, path, dataCanopyField, onRemove, }) => {
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
+export const ObjectField = ({ label, description, fields, value, onChange, renderField, path, dataCanopyField, onRemove, }) => {
     const current = value ?? {};
-    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [(label || onRemove) && (_jsxs(Group, { justify: "space-between", children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "neutral.8", children: label })), onRemove && (_jsx(Button, { size: "xs", variant: "subtle", color: "red", onClick: onRemove, children: "Clear" }))] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
+    const descriptionBaseId = useId();
+    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", ...groupDescriptionProps(descriptionBaseId, description), children: _jsxs(Stack, { gap: "sm", children: [(label || onRemove) && (_jsxs(Group, { justify: "space-between", children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "neutral.8", children: label })), onRemove && (_jsx(Button, { size: "xs", variant: "subtle", color: "red", onClick: onRemove, children: "Clear" }))] })), _jsx(FieldDescription, { baseId: descriptionBaseId, description: description }), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
                         const fieldPath = [...path, field.name];
                         return (_jsx("div", { children: renderField(field, current[field.name], (next) => onChange({ ...current, [field.name]: next }), fieldPath) }, formatCanopyPath(fieldPath)));
                     }) })] }) }));

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

@@ -7,6 +7,7 @@ export interface ReferenceOption {
 export interface ReferenceFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     options?: ReferenceOption[];
     collections?: string[];
     entryTypes?: string[];

package/dist/editor/fields/ReferenceField.js

@@ -6,7 +6,8 @@ import { IconAlertCircle } from '@tabler/icons-react';
 import { createApiClient } from '../../api/client.js';
 import { useOptionalApiClient } from '../context/index.js';
 import { getErrorMessage } from '../../utils/error.js';
-export const ReferenceField = ({ id, label, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', value, onChange, multiple, dataCanopyField, }) => {
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
+export const ReferenceField = ({ id, label, description, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', value, onChange, multiple, dataCanopyField, }) => {
     // 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
@@ -101,10 +102,10 @@ export const ReferenceField = ({ id, label, options: staticOptions, collections,
         setRetryCount((count) => count + 1);
     };
     if (loading) {
-        return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _jsx(Loader, { size: "sm", "data-testid": `reference-loading-${dataCanopyField}` })] }));
+        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}`, children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _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 (_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, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: "Select reference\u2026", size: "sm" })) : (_jsx(Select, { id: inputId, label: label, data: options, value: normalizedValue, onChange: (next) => onChange(next ?? ''), searchable: true, clearable: true, placeholder: "Select reference\u2026", size: "sm" })) }));
+    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" })) }));
 };

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

@@ -6,6 +6,7 @@ interface SelectOption {
 export interface SelectFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     options: SelectOption[];
     value: string | string[];
     onChange: (value: string | string[]) => void;

package/dist/editor/fields/SelectField.js

@@ -1,7 +1,7 @@
 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, options, value, onChange, multiple, placeholder = 'Select…', dataCanopyField, }) => {
+export const SelectField = ({ id, label, description, options, value, onChange, multiple, placeholder = 'Select…', dataCanopyField, }) => {
     const normalizedValue = multiple
         ? Array.isArray(value)
             ? value
@@ -11,5 +11,5 @@ export const SelectField = ({ id, label, options, value, onChange, multiple, pla
             : '';
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, children: [multiple ? (_jsx(MultiSelect, { id: inputId, label: label, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: placeholder, size: "sm" })) : (_jsx(Select, { id: inputId, label: label, 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." }))] }));
+    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." }))] }));
 };

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface StringListFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string[];
     onChange: (value: string[]) => void;
     dataCanopyField?: string;

package/dist/editor/fields/StringListField.js

@@ -7,10 +7,10 @@ import { TagsInput } from '@mantine/core';
  * 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.
  */
-export const StringListField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const StringListField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(TagsInput, { id: inputId, label: label, value: value, size: "sm", onChange: onChange, 
+    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

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface TextFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;

package/dist/editor/fields/TextField.js

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

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

@@ -2,6 +2,7 @@ import React from 'react';
 export interface ToggleFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: boolean;
     onChange: (value: boolean) => void;
     dataCanopyField?: string;

package/dist/editor/fields/ToggleField.js

@@ -1,8 +1,11 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
-import { Switch } from '@mantine/core';
-export const ToggleField = ({ id, label, value, onChange, dataCanopyField, testId, }) => {
+import { Stack, Switch } from '@mantine/core';
+import { FieldDescription, fieldDescriptionId } from './FieldDescription.js';
+export const ToggleField = ({ id, label, description, value, onChange, dataCanopyField, testId, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(Switch, { id: inputId, label: label, checked: value, onChange: (e) => onChange(e.currentTarget.checked), size: "md", "data-canopy-field": dataCanopyField, wrapperProps: testId ? { 'data-testid': testId } : undefined }));
+    // 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 })] }));
 };

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

@@ -36,8 +36,9 @@ export const InsertEntryLink = ({ onInsert }) => {
     }, [filtered]);
     const handleSelect = (entry) => {
         const rawText = entry.label || entry.slug || 'Link';
-        // Escape backslashes first, then markdown-special characters in link text
-        const linkText = rawText.replace(/\\/g, '\\\\').replace(/([[\]()])/g, '\\$1');
+        // Escape backslashes first, then characters that end the link text or that
+        // the editor parses as MDX (`{` opens an expression, `<` a JSX tag).
+        const linkText = rawText.replace(/\\/g, '\\\\').replace(/([[\]()<>{}])/g, '\\$1');
         const markdown = `[${linkText}](entry:${entry.contentId})`;
         onInsert(markdown);
         setOpened(false);

package/dist/editor/fields/mdx-jsx-support.d.ts

@@ -0,0 +1 @@
+export declare function mdxJsxPlugins(): import("@mdxeditor/editor").RealmPlugin[];

package/dist/editor/fields/mdx-jsx-support.js

@@ -0,0 +1,137 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { NestedLexicalEditor, UnrecognizedMarkdownConstructError, addImportVisitor$, importVisitors$, isMdastHTMLNode, isMdastJsxNode, jsxPlugin, realmPlugin, } from '@mdxeditor/editor';
+function childrenOf(node) {
+    return 'children' in node && Array.isArray(node.children) ? node.children : [];
+}
+function describeAttribute(attribute) {
+    if (attribute.type === 'mdxJsxExpressionAttribute')
+        return '{…}';
+    if (attribute.value === null || attribute.value === undefined)
+        return attribute.name;
+    if (typeof attribute.value === 'string')
+        return `${attribute.name}="${attribute.value}"`;
+    return `${attribute.name}={…}`;
+}
+/**
+ * Shows an element's tag and attributes read-only (they are edited as source)
+ * and edits its children, inline or block per the parsed node: one `*`
+ * descriptor serves both, and a block editor rejects inline children.
+ */
+const CatchAllJsxEditor = ({ mdastNode }) => {
+    const inline = mdastNode.type === 'mdxJsxTextElement';
+    const tag = [mdastNode.name ?? '', ...mdastNode.attributes.map(describeAttribute)]
+        .join(' ')
+        .trim();
+    const Wrapper = inline ? 'span' : 'div';
+    return (_jsxs(Wrapper, { className: inline ? 'canopy-mdx-jsx canopy-mdx-jsx-inline' : 'canopy-mdx-jsx', children: [_jsx("span", { className: "canopy-mdx-jsx-tag", "data-testid": "mdx-jsx-tag", title: tag, children: `<${tag}>` }), mdastNode.children.length > 0 ? (_jsx(NestedLexicalEditor, { block: !inline, getContent: (node) => node.children, getUpdatedMdastNode: (node, children) => ({ ...node, children }) })) : null] }));
+};
+const catchAllJsxDescriptor = {
+    name: '*',
+    kind: 'flow',
+    props: [],
+    hasChildren: true,
+    Editor: CatchAllJsxEditor,
+};
+const isStringAttribute = (attribute, name) => attribute.type === 'mdxJsxAttribute' &&
+    attribute.name === name &&
+    typeof attribute.value === 'string';
+// MDXEditor's export merges an HTML element's lone `span` child into it, and
+// throws if either one's `className` or `style` is not a string.
+function breaksSpanCollapse(node) {
+    const [onlyChild, ...rest] = node.children;
+    if (rest.length > 0 || onlyChild === undefined)
+        return false;
+    if (onlyChild.type !== 'mdxJsxTextElement' || onlyChild.name !== 'span')
+        return false;
+    return ['className', 'style'].some((name) => {
+        const own = node.attributes.find((a) => a.type === 'mdxJsxAttribute' && a.name === name);
+        const child = onlyChild.attributes.find((a) => a.type === 'mdxJsxAttribute' && a.name === name);
+        return (own !== undefined &&
+            child !== undefined &&
+            !(isStringAttribute(own, name) && isStringAttribute(child, name)));
+    });
+}
+/**
+ * MDXEditor's image plugin drops an `<img>` with no `src`, keeps only string
+ * values, lowercases the attribute names it does not model, and parses width
+ * and height as integers.
+ */
+function roundTripsImage(node) {
+    return (node.attributes.some((a) => isStringAttribute(a, 'src') && a.value !== '') &&
+        node.attributes.every((attribute) => {
+            if (attribute.type !== 'mdxJsxAttribute' || typeof attribute.value !== 'string')
+                return false;
+            if (attribute.name === 'width' || attribute.name === 'height') {
+                return /^\d+$/.test(attribute.value);
+            }
+            return attribute.name === attribute.name.toLowerCase();
+        }));
+}
+// Why MDXEditor cannot round-trip this JSX element, or null if it can. A
+// fragment has no name, which MDXEditor's HTML handling throws on.
+function unsupportedJsx(node) {
+    if (!isMdastJsxNode(node))
+        return null;
+    if (node.name === null)
+        return 'fragments (<>…</>)';
+    // `img` is the image plugin's, not in MDXEditor's HTML tag list.
+    if (node.name === 'img')
+        return roundTripsImage(node) ? null : 'this <img>';
+    if (isMdastHTMLNode(node) && breaksSpanCollapse(node)) {
+        return `<${node.name}> wrapping a <span>, with an {expression} class or style`;
+    }
+    return null;
+}
+/** Typed `string` because the mdast node union this package resolves omits the ESM node. */
+const ESM_NODE_TYPE = 'mdxjsEsm';
+/** Node types the table visitor imports itself, so they have no visitor of their own. */
+const CONSUMED_BY_PARENT_VISITOR = new Set(['tableRow', 'tableCell']);
+/**
+ * Reports through `onError`, at import, what MDXEditor would otherwise lose
+ * silently: `import`/`export` lines (its visitor for them is a no-op), elements
+ * `unsupportedJsx` rejects, and content with no visitor inside a JSX element or
+ * table, whose children nested editors import later, only logging a failure and
+ * writing partial children back on edit. It throws an error class MDXEditor's
+ * import reports; any other error would crash the editor.
+ */
+const roundTripGuardPlugin = realmPlugin({
+    init(realm) {
+        const guard = {
+            priority: 100,
+            testNode: (node) => node.type === ESM_NODE_TYPE || node.type === 'table' || isMdastJsxNode(node),
+            visitNode({ mdastNode, descriptors, actions }) {
+                if (mdastNode.type === ESM_NODE_TYPE) {
+                    throw new UnrecognizedMarkdownConstructError('import/export statements cannot be edited in the rich-text editor');
+                }
+                const reject = (node) => {
+                    const reason = unsupportedJsx(node);
+                    if (reason !== null) {
+                        throw new UnrecognizedMarkdownConstructError(`${reason} cannot be edited in the rich-text editor`);
+                    }
+                };
+                reject(mdastNode);
+                const visitors = realm.getValue(importVisitors$).filter((visitor) => visitor !== guard);
+                const hasVisitor = (node) => visitors.some((visitor) => typeof visitor.testNode === 'string'
+                    ? visitor.testNode === node.type
+                    : visitor.testNode(node, descriptors));
+                const check = (node) => {
+                    for (const child of childrenOf(node)) {
+                        reject(child);
+                        if (!CONSUMED_BY_PARENT_VISITOR.has(child.type) && !hasVisitor(child)) {
+                            const where = isMdastJsxNode(mdastNode) ? `<${mdastNode.name ?? ''}>` : 'A table';
+                            throw new UnrecognizedMarkdownConstructError(`${where} contains ${child.type} content the rich-text editor cannot edit`);
+                        }
+                        check(child);
+                    }
+                };
+                check(mdastNode);
+                actions.nextVisitor();
+            },
+        };
+        realm.pub(addImportVisitor$, guard);
+    },
+});
+export function mdxJsxPlugins() {
+    return [jsxPlugin({ jsxComponentDescriptors: [catchAllJsxDescriptor] }), roundTripGuardPlugin()];
+}